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Preface 



The DECnet-RSX Programmer's Reference Manual explains DECnet program- 
ming concepts and describes the DECnet-RSX calls for the following program- 
ming functions: 

■ Intertask communication 

■ Remote file access 

■ Task control 

■ Direct line access (DLX) 

The DECnet-RSX software supports intertask communication calls for MACRO- 
11, FORTRAN 77, COBOL, and BASIC-PLUS-2 programming; remote file access 
calls for FORTRAN 77, COBOL, and BASIC-PLUS-2; task control calls for 
FORTRAN 77; and QIO calls for the DLX user interface. 

The manual also includes information on writing applications for Local Area 
Transport (LAT) application terminals. 

Throughout the manual, the term "DECnet-RSX" refers to all the software that 
you receive in your DECnet-RSX distribution kit. 

Intended Audience 

This manual is for users who write network programs that run on DECnet- 1 IM, 
DECnet- 1 IM-PLUS, DECnet- 1 IS, and DECnet-Micro/RSX systems. 
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structure of This Manual 



The manual is organized as follows 
Chapter 1 

Chapter 2 

Chapter 3 



Provides introductory information about intertask communi- 
cation, remote file access, and task control operations. 

Describes the DECnet-RSX MACRO- 1 1 programming facili- 
ties for intertask communication macros. 



Describes the DECnet-RSX FORTRAN, COBOL, and BASIC- 
PLUS-2 programming facilities for intertask communication, 
remote file access, and FORTRAN task control. 

Chapter 4 Describes the DECnet-RSX Direct Line Access (DLX) pro- 

gramming facilities and QIO calls for tasks using the Ethernet. 

Chapter 5 Describes the DECnet-RSX Direct Line Access (DLX) pro- 

gramming facilities and QIO calls for tasks using point-to- 
point and multipoint lines. 

Chapter 6 Describes programming facilities for tasks that use Local Area 

Transport (LAT) application terminals. 

Appendix A Contains the network disconnect or reject reason codes. 

Appendix B Defines the Digital object type code values. 

Appendix C Summarizes remote file access error/completion codes. 

Appendix D Contains the MACRO- 1 1 connect block offset and code defi- 

nitions. 

Appendix E Contains the FORTRAN, COBOL, and BASIC-PLUS-2 net- 

work error/completion codes. 

Appendix F Contains the MACRO- 1 1 network error/completion codes. 

Appendix G Provides information on multicast addresses, protocol types, 

and protocol identifiers to use with Ethernet applications. 

Appendix H Describes DLX completion codes for characteristics opera- 

tions in Ethernet applications. 
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The following manuals are part of the DECnet-RSX documentation set: 



■ DECnet-RSX Network Management Concepts and Procedures 

■ DECnet-RSX Guide to Network Management Utilities 

■ DECnet-RSX Guide to User Utilities 

■ DECnet-RSX Network Generation and Installation Guide 
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Acronyms 

The following acronyms are used in this manual: 



AST 


A^vfiphrnnons svstptn trar> 






Til "X" 


J-ZllCCl. LilllC /\i,CCSS VjUllUHJllCl 




nisz v^uiimji C5ysiciii 


MOP 


Maintenance Operation Protocol 


NETFOR.OLB 


DECnet high-level language library 


NETLIB.MLB 


DECnet MACRO- 1 1 library 


NFAR 


Network File Access Routine 


PSW 


Processor status word 


QIO 


Queued input/output call 



Graphic Conventions 

Convention l\1eaning 

Special type This special type shows examples of user input (in red) or sys- 
tem output (in black). 

UPPERCASE Uppercase letters indicate characters to type exactly as 

shown. You can type the text in upper- or lowercase. You can 
abbreviate uppercase words to the first three or more unique 
characters. 

lowercase italics Lowercase italics indicate variables for which you specify or 
the system supplies the actual values. 

[ ] Square brackets enclose optional data. If the brackets enclose 

a vertical list of options, you can specify only one option. Do 
not type the brackets when you enter the call. 

{ } Braces enclose options, from which you must choose one and 

only one. Do not type the braces when you enter the call. 

( ) Parentheses enclose a set ofoptions. You must specify both 

or neither of them. Do not type the parentheses when you 
enter the call. 
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Convention 



Meaning 



( key ) 



This symbol indicates a key to press, f ctrux i indicates that 
you press the CONTROL key and the key represented by x 
together. 



PRST2=5 



Ellipses represent an omission. To emphasize the important 
information, examples may omit some of the user input or 
system output 



CALL BFMTl 

All values that appear in this manual are decimal unless otherwise noted. 

Certain additional conventions apply in specific chapters. Section 2.4 describes 
specific conventions for MACRO- 1 1 calls. Section 3 7 describes specific conven- 
tions for FORTRAN, COBOL, and BASIC-PLUS-2 calls. 
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Introduction 



DECnet-RSX software extends the RSX operating systems for the PDP-1 1 . With 
DECnet-RSX, you can write programs that exchange data with programs on 
other DECnet systems in the network that run under RSX or other operating sys- 
tems. This manual describes the network programming functions that you can use 
with the MACRO-1 1, FORTRAN 77, COBOL, and BASIC-PLUS-2 languages. 

Programs using DECnet-RSX can have tasks running on different nodes that 
exchange data using intertask communication, remote file access, or remote task 
control. 

■ Intertask communication. User tasks on different nodes can exchange 
messages and data by issuing a series of DECnet communications calls. DEC- 
net software lets you perform task-to-task communication, whether or not 
both tasks are written in the same programming language or both nodes are 
under the same operating system. For example, an RSX FORTRAN 77 pro- 
gram can communicate with a VMS BASIC-PHJS-2 program. 

■ Remote file access. Remote file access programs can access sequential 
files for reading, writing, and appending records to remote files. They can 
also delete remote files. 

Programming remote file access operations on a remote RSX node is similar 
to programming local I/O operations. For a remote node under another 
operating system, your program's access is determined by what functions its 
source language provides and the remote file system supports. 

■ Remote task control. A FORTRAN program can control the execution of 
installed tasks on remote RSX or IAS DECnet nodes. The program can cause 
immediate execution of a remote task, schedule it for later or periodic exe- 
cution, abort it, or cancel its scheduling. 
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You can perform functions on cooperating local and remote nodes or simply at 
the local node. For example, a task can issue MACRO- 11 DECnet calls to 
exchange data with another task on the same node. This lets you debug an RSX 
program locally before running it at a remote node. 

1 . 1 Intertask Communication Conventions 

To refer to a call common to all four languages that DECnet-RSX supports, this 
manual uses the call's first three letters, followed by x. The x represents the part 
of the call name that varies by programming language. With MACRO-11, you 
replace the x with the $ symbol. With FORTRAN, COBOL, and BASIC-PLUS-2, 
you replace the x with the letters NT. 

In this manual, the term "macro" refers to MACRO-11 calls; the term "call" 
refers to FORTRAN, COBOL, and BASIC-PLUS-2 calls. 

Example: 

OPN:!c (generic representation) 
OPN$ (MACRO-11) 

OPNNT (FORTRAN, COBOL, or BASIC-PLUS-2) 

OPNjc is the first DECnet call a task issues for any DECnet session. A session 
includes all intertask communication calls issued between the OPNa: call and the 
CLSjccall. 

Table 1-1, in Section 1.3, provides an alphabetical list of the DECnet intertask 
communication calls, and describes the function and expected result of each. 

1 .2 lntertasl( Communication Concepts 

This section explains the following basic intertask communication concepts: 

■ Establishing an active network task 

■ Establishing a logical link 

■ Building a connect block 

■ Getting data from the network data queue 

■ Sending and receiving messages 
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■ Sending interrupt messages 

■ Checking completion status information 

■ Terminating activity on a logical link 

■ Closing a network connection 

1.2.1 Establishing an Active Networic Tasic 

Before any task can exchange data using intertask communication calls, it must be 
an active network task. A task is active if it is running and has issued an open 
(OPN:<:) call. An OPNa: call connects the task to the network. It can also establish 
the task's network data queue. 

Your task requires Logical Unit Numbers (LUNs) assigned to NS:, the network 
pseudodevice driver: a network data queue (mailbox) LUN and a LUN for each 
logical link. 

The network data queue (mailbox) LUN specifies the queue from which your task 
retrieves network messages. 

You can define the network data queue LUN by including the value as an argu- 
ment to the OPN$/OPNNT call or you can use the value of the symbol .MBXLU. 
You can define the value of .MBXLU at task build time; with MACRO- 1 1 , you can 
also define it at assembly time. The .MBXLU definition is referenced only if you 
omit the LUN argument in the call; so define a particular network data queue LUN 
in only one place. 

To define .MBXLU at task build time, issue the following task build option: 
GBLDEF=.MBXLU:a: 

This instructs the task builder to define all global references to .MBXLU as the 
integer value represented by x. 

Using MACRO- 11 , you can choose to define .MBXLU at assembly time. To define 
the LUN locally in your source code to a value represented by x, put the following 
in each source module: 

. MBXLU=a: 

To define the LUN globally, include this statement in a single source module: 
. MBXLU==^ 
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The task builder will define references to .MBXLU in each source module in your 
task to the value of x. 

A task can use only one network data queue LUN. In MACRO- 1 1 tasks, you can 
specify a network data queue LUN with the following calls: SPA$ (specify a user 
AST routine), GND$ (get network data), REJ$ (reject a logical link request), CLS$ 
(end the task's network operations), and GLN$ (get local node information). You 
must specify the same LUN that you specified in the OPN$ call, or the macro com- 
pletes with a privilege error (lE.PRI). 

Choose only one of these command techniques for defining .MBXLU. However, if 
you do not define .MBXLU, the task builder returns an undefined reference warn- 
ing message. If you run the task and ignore the warning, the operating system 
rejects the macro calls (OPN;c, SPA$, GND$, REJ$, CLS$, and GLN$) with a direc- 
tive status error indicating an invalid LUN. The task builder causes undefined ref- 
erences to default to zero (0). You cannot define .MBXLU with a value of 0; is an 
invalid logical unit number. 

Issuing a CLS$ call to terminate network operations for a MACRO- 1 1 task frees all 
network logical unit numbers and aborts the task's logical links. You can issue the 
CLS$ call in any of the three CLS$ formats - CLS[W]$, CLS[W]$E, and CLS[W]$S. 

If a LUN is not assigned to NS:, any network directive is returned with the "illegal 
function code" status. 

1 .2.2 Establishing a Logical Link 

To exchange data, a logical link must exist between two active network tasks. A 
logical link is a logical path between two cooperating tasks that agree to commu- 
nicate. When the link is established, a user task can send and receive messages. 
Figure 1-1 illustrates the flowchart process for establishing a logical link. 
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Figure 1 -1 : Establishing a Logical Link 
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The task requesting the logical link is the source task. The task receiving the 
request is the target task. The distinction between source and target task applies 
only during the connection sequence. Once the logical link is established, both 
tasks have equal access to it. 

Tasks at both ends of the link must specify a logical unit number (LUN) for the 
link. Each task assigns a link LUN to identify the link to the tasks and network. The 
tasks at both ends need not use the same LUN for a link. 

1 .2.3 Building a Connect Block 

Before the source task can issue a request to connect to another task, it must build 
a connect block. A connect block contains a destination descriptor, source 
descriptor, and optionally, access control information and user-supplied data. 

1.2.3.1 Destination Descriptor 

The destination descriptor identifies the destination task by task name or object 
type number. 

When two tasks communicate, they are considered to be two objects. A task can 
be set up as a named or numbered object: 

■ A named object is an installed user-defined task to which you connect by 
specifying a name. The object type number for a named object is 0. 

■ A numbered object is an installed user-defined task or DECnet task to which 
you connect by specifying an object type number. The object type numbers 
for numbered objects range from 1 to 255, with 1 to 127 reserved for DEC- 
net tasks and 128 to 255 reserved for user tasks. 

For information on defining objects, see the DECnet-RSX Network Management 
Concepts and Procedures manual. 

1 .2.3.2 Source Descriptor 

The source descriptor contains information that the DECnet software on the 
source node supplies. The information includes either 

■ The source node name and task name of a named object or the source node 
name and task object number of a numbered object. 

■ The source node name and the user name of the person running the task. 

The target task can use the source descriptor to determine whether it wants to 
establish communications. 
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1.2.3.3 Access Control Information 

Access control information defines your access rights at the remote node. Each 
target system performs access control verification according to its conventions. If 
the target node is equipped to verify access control information, it does so before 
passing the connect request to the target task. For information on access control 
verification, see the DECnet-RSX Network Management Concepts and Proce- 
dures mznusLl. 

1 .2.3.4 Optional Data l\/lessages 

When the source task issues a connect request, you can include a data message of 
up to 16 characters in the connect block. If the connect (CONa:) call contains the 
location and length of a block of user data, the source node appends that block to 
the connect block. 

1 .2.4 Getting Data from the Network Data Queue 

Once a task is connected to the network, it has a network data queue. The soft- 
ware on the connected task's node places all incoming connect request messages, 
interrupt messages, user disconnect messages, user abort messages, and network 
abort messages on the task's network data queue. To get these messages, the task 
issues a get network data (GNDjc) call. A task should begin monitoring its network 
data queue as soon as the open call completes successfully. 

The get network data call ordinarily returns the first message on the queue on a 
first-in, first-out basis. However, the GNDx call has the following options: 

■ Remove the first message on the queue and place it in the message buffer. 

■ Remove the first message of a specified type for any logical link and place it 
in the message buffer. 

■ Remove the first message for a specified logical link regardless of the mes- 
sage type and place it in the message buffer. 

■ Remove the first message of a specified type for a specified logical link and 
place it in the message buffer. 

■ Determine the type, length, and associated logical link of any message on the 
queue without removing it from the queue. This allows you to assign an 
appropriate buffer size in a subsequent GND.x: call that performs one of the 
four options just listed. 
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1 .2.5 Sending and Receiving l\/lessages 

Once a logical link is established between two tasks, both tasks can send and 
receive messages. DECnet distinguishes between data and nondata messages. 
Data messages go directly to a buffer provided by the receiving task. Nondata 
messages go to a task's network data queue. Nondata messages are unsolicited 
high priority messages that inform the receiving task of an event, such as an inter- 
rupt or disconnect request. 

To send a data message, a task issues a send (SNDjc) call. The send call must specify 
the LUN that the connect or accept call assigned. It also specifies the location and 
length of the data message buffer. A send call completes when the receiving node 
acknowledges to the sending node that it received a message correctly. 

To receive a data message, a task issues a receive (REC:x:) call. The receive call must 
specify the LUN that the connect or accept call assigned. It also specifies the loca- 
tion and length of the data message buffer. A receive call completes when the data 
message is placed in the specified data message buffer. If the data message buffer is 
not large enough, the receive call completes with a data overrun condition and 
the excess data is lost; the I/O status indicates the overrun in such cases. Another 
receive call is then required to receive the next data message. 

To send a high priority nondata message, a task issues an abort (ABT:xr), disconnect 
(DSCx), or interrupt (XMLxr) call. To receive a high priority nondata message, a 
task issues a get network data (GNDjc) call. 

1 .2.6 Sending interrupt iVIessages 

A task can send interrupt messages to another task. Usually an interrupt message 
informs the receiving task of some unusual event in the sending task. An interrupt 
(XMLxr) message can be up to 16 bytes long. In the interrupt call, specify the LUN 
assigned in the connect or accept call. Also specify the location and length of the 
message buffer. 

An interrupt call completes when the receiving node acknowledges to the send- 
ing node that it received the message. The receiving node software places the 
interrupt message on the receiving task's network data queue. The receiving task 
must issue a get network data call to remove the message from the queue and 
place it in the task's message buffer. 

A task can have only one interrupt message outstanding on a logical link. Until the 
call completes, any subsequent attempt to send another interrupt message on that 
same link will return an error code in the I/O status word. 
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1 .2.7 Checking Completion Status Information 

Each macro or call can include an argument that specifies the address of a 2 -word 
status block. The status block returns the status of a completed call. Include this 
argument so that you can check completion status. You can use the same block 
for successive I/O requests, but only by one macro or call at a time. If concurrent 
I/O requests attempt to use the same status block, unpredictable results occur. 

The first status word contains: 

■ A zero if the called macro or subroutine has not completed 

■ A positive value if the called macro or subroutine produced the desired 
results 

■ A negative value if the called macro or subroutine did not produce the 
desired results 

The second status word contains further information about the completion. For 
example, in a successful data transmission, it returns the number of bytes trans- 
mitted. 

1 .2.8 Terminating Activity on a Logical Link 

Any task can terminate activity on a logical link at any time by issuing a discon- 
nect or abort call: 

■ A disconnect (DSCx) call terminates transmissions over the logical link after 
all data transmissions and interrupts have been sent. 

■ An abort (ABTjc) call disconnects the logical link immediately, even if mes- 
sages are queued for transmission. 

The receiving node software places the termination message on the receiving 
task's network data queue. The receiving task must issue a get network data call to 
retrieve the message. 

Both disconnect and abort calls can specify the location and length of a user data 
message of up to 16 bytes for the receiving task. 

The disconnect call must specify the logical unit number (LUN) assigned in the 
connect or accept call. A disconnect call allows node software to complete all 
pending transmits for the issuing task before disconnecting the logical link. Dur- 
ing this time, the issuing task continues to receive messages. When the last mes- 
sage is transmitted, however, any remaining receive calls complete with an abort 
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condition. When the link is disconnected, the LUN is freed. A task can use that 
LUN in subsequent connect or accept calls. 

The abort call must specify the logical unit number (LUN) assigned in the connect 
or accept call. An abort call causes the node software to immediately abort all 
pending transmits and receives and disconnect the link. The LUN is freed and a 
task can use that LUN in subsequent connect or accept calls. 

1 .2.9 Closing a Network Connection 

To close a task's network connection, issue a close (CLSat) call. The close call 
informs the node software that the task no longer requires network services and 
purges the task's network data queue. Any active LUNs are deactivated and freed 
for use if the task subsequently issues an open (OPN:xr) call. 

If data remains in the terminating task's network data queue when the close call is 
issued, the task receives any connect requests that remain in its network data 
queue if it subsequently issues an open call within a short period of time. Data of 
other types, such as interrupt, disconnect, and abort messages, are discarded. 

1.2.10 Using tlie Wait Option 

Many macros and calls allow you to use the wait option. Including W in a call 
(such as GNDW$ or GNDNTW) delays execution of the calling task until the call 
completes. The calling task then continues at the instruction immediately follow- 
ing the call. Without the wait option, the call executes asynchronously. 

In a MACRO- 1 1 call for which you specify the wait option, an event flag is man- 
datory. If you omit the event flag, the call completes as a normal asynchronous 
call. 

1 .2.1 1 Using the AST and WAITNT Options 

An asynchronous system trap (AST) in a MACRO- 1 1 call causes the AST to exe- 
cute when the call completes. In FORTRAN, COBOL, and BASIC-PLUS-2, the 
WAITNT call instead determines when a call completes. 

1.2.12 Using the Flow Control Option 

A network program requires buffer space for temporary message storage. For 
example, a program keeps a copy of each message that it sends over the link in 
buffer space until the receiver acknowledges the message. A program also holds 
buffer space for receiving inbound messages. 



1-10 



DECnet-RSX Programmer's Reference Manual 



DECnet provides flow control mechanisms that prevent the overflow of available 
buffer space. Sending and receiving tasks are synchronized so that a source task 
transmits data only if the target task has issued a receive call and has available 
buffer space. 

With MACRO- 11 tasks, DECnet-RSX also provides a special NOFLOW option 
that disables flow control mechanisms. The NOFLOW option can help in attain- 
ing a higher level of network performance, but you must use it with caution. 
Without flow control, a source task can send data whether or not a buffer is avail- 
able to receive it. If the target task does not have adequate buffering for the 
incoming data, some data segments will be discarded. The software must request 
retransmission of each discarded segment, after a timeout. This significantly 
degrades network performance. If you choose the NOFLOW option, maintain 
adequate buffering at the target task to compensate for the loss of send/receive 
synchronization. The communicating programs should be appropriately written. 

The NOFLOW option is desirable when: 

■ A program's User layer protocol already includes control mechanisms or 
acknowledgment-signaling mechanisms . 

■ The flow of data is predictable, and the program can handle the flow. 

NOTE 

It is inadvisable to use the NOFLOW option in the ini- 
tial stages of developing a network program. Wait 
until after you test the communicating programs and 
adequately synchronize the data flow. 

You can set either end of the logical link to FLOW or to NOFLOW control inde- 
pendently. Set the NOFLOW control option within the CONx and ACCx calls. 
Flow control is the default. 

1 .3 Summary of Intertask Communication Calls 

Table 1-1 lists the intertask communication calls. The first column of the table 
lists the call name. MACRO- 1 1 macro call names have the form nam$ and FOR- 
TRAN, COBOL, and BASIC-PLUS-2 call names have the form namNT, where 
nam represents the specific call. The second column defines the function of the 
call. The third column describes the result of the call's successful execution. 
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Table 1 -1 : DECnet Communication Calls 



Call 



Function 



Normal Action 



ABT$ 
ABTNT 



ACC$ 
ACCNT 



BACC 
BACCL 



BFMTO 
BFMTl 



CLS$ 
CLSNT 



CON$ 
CONNT 



Abort a logical link 



Accept a logical 
link request 



Build access control 
information area 



Build a format 
descriptor block 



Close the network 
connection — end the 
task's network 
operations 

Request a logical 
link connection 



Transmits a nondata abort message over the 
logical link. The DECnet software on the 
receiving node delivers the abort message to 
the receiving task's network data queue. 

Notifies the DECnet software on the target 
node that the target task accepts a logical link 
request. The DECnet software then sends the 
acceptance notification to DECnet software on 
the source node. The source node DECnet soft- 
ware delivers the accept message to the status 
block that the source task specified in the 
com or CONNT call. 

Builds the access control information for a 
connect block. Use BACC for a short connect 
block, and BACCL for a long connect block. A 
subsequent CONNT call delivers the contents 
of this block to the DECnet software on the tar- 
get node. This call does not transmit user data 
over a logical link. 

Builds a destination descriptor for the connect 
block. A format destination descriptor 
describes the target task by object code. A for- 
mat 1 destination descriptor describes the tar- 
get task by name. This call does not transmit 
user data over a logical link. A subsequent 
CONNT call delivers the contents of this block 
to the DECnet software on the target node. 

Sends the close request to the DECnet software 
on the issuing task's node. This call does not 
transmit user data over a logical link. 

Sends a high priority nondata connect message 
and connect block over a temporary logical 
link to the target node's DECnet software. If 
the target task is an active network task, the 
connect request is delivered to its network 
data queue. The connect block is delivered to a 
mailbox as a result of a subsequent get network 
data call (GND$ or GNDNT). 
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Table 1 -1 (Cont.): DECnet Communication Calls 



Call 


Function 


Normal Action 


CONB$$ 


Build a connect block 
(short) 


Builds a connect block that a subsequent C6N$ 
call delivers to the DECnet software on the tar- 
get task. This connect block accepts a user ID 
of up to 16., password of up to 8., and account 
number of up to 16. bytes. This call does not 
transmit data. 


CONL$$ 


Build a connect block 
(long) 


Builds a connect block that a subsequent CON$ 
call delivers to the DECnet software on the tar- 
get task. This connect block accepts a user ID, 
password, and account number of up to 39. 
bytes each. This call does not transmit data. 


DSC$ 
DSCNT 


Disconnect the 
logical link 


Transmits a nondata disconnect message over 
the logical link. The DECnet software on the 
receiving task's node delivers the disconnect 
message to the task's network data queue. 


GLN$ 
GLNNT 


Get local node data: 
node name and 
transmission segment 
size 


Delivers local node information to the buffer 
that an argument of the call specifies. This call 
does not transmit user data over a logical link. 


GND$ 
GNDNT 


Get network data from 
tasks 's network data 
queue 


Stores data from the network data queue in the 
location that arguments of the call in the issu- 
ing task specify. This call does not transmit 
user data over a logical link. 


OPN$ 
OPNNT 


Open the network 
connection — create 
the task's network 
data queue 


Delivers the open request to the DECnet soft- 
ware on the issuing task node. This call does 
not transmit user data over a logical link. 


REC$ 
RECNT 


Request to receive 
data over the logical 
link 


Receives a data message that another task's 
DECnet send call initiated. When the receive 
call completes, the DECnet software on the 
issuing task node sends a notification message 
to the status block specified in the call. This 
call does not transmit user data over a logical 
link. 


REJ$ 
REJNT 


Reject a logical link 
request 


Sends rejection notification over the tempo- 
rary logical link from the DECnet software on 
the target task's node to the DECnet software 
on the source node. The source node's DECnet 
software delivers the reject notice to the status 
block that the source task's CON$ or CONNT 
call specified. 



(continued on next page) 
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Table 1-1 (Cont.): DECnet Communication Calls 



Call 



Function 



Normal Action 



SND$ 
SNDNT 



SPA$ 



WAITNT 



XMI$ 
XMINT 



Request to send a data 
message over the 
logical link 



Specify the location 
of a user- written 
asynchronous system 
trap (AST) routine 

Wait for the completion 
of any other DECnet 
communications call 



Request to send an 
interrupt message 
over the logical link 



Transmits the data message over the logical 
link to the DECnet software on the receiving 
task node. When the receiving DECnet soft- 
ware delivers the message to the area specified 
in the receiving task's receive call, it returns a 
completion status message to the sending 
DECnet software, which delivers it to the 
status block specified in the send call. 

Transfers control to the AST routine when a 
nondata message is placed on the task's net- 
work data queue. This call does not transmit 
user data over a logical link. 

Suspends task execution until completion of a 
previously-issued call that included a wait 
option. This call does not transmit user data 
over a logical link. 

Transmits a high priority nondata interrupt 
message over the logical link. The DECnet soft- 
ware on the receiving node delivers the inter- 
rupt message to the receiving task's network 
data queue. 



4 DECnet-RSX Remote File Access Operations 

Using DECnet-RSX remote file access facilities, you can write a FORTRAN, 
COBOL, or BASIC-PLUS-2 program that performs the following file access oper- 
ations for sequential files only: 

■ Open or create a remote file 

■ Read and write records to a remote file 

■ Append records to a remote file 

■ Close, purge, or delete a remote file 
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DECnet-RSX file access facilities have similar features to those of DECnet-RSX 
intertask communication facilities. 

■ The file access facilities are implemented by means of calls to subroutines. 

■ The task that requests file access is called the source task, and the task that 
accepts or rejects the request is called the target task. 

■ Acceptance of a file access request creates a logical link between the source 
and target tasks. Then the file access process begins. 

Incoming file access requests are translated into calls to the file system at the tar- 
get node. The resulting file data is sent back to the accessing task. The accessing 
task then reformats the data as the system requires. The DECnet software 
establishes the logical link for file access operations; much of the connection pro- 
cess is therefore transparent, in contrast to intertask communication. After com- 
pleting file access operations, the logical link is disconnected. 

Section 3-9 discusses remote file access operations. 



1 .5 DECnet-RSX Task Control 

DECnet-RSX task control lets you write tasks in FORTRAN that: 

■ Execute an installed task on a remote node according to a set schedule, using 
the RUNNCW call 

■ Abort an executing task on a remote node, using the ABONCW call 

■ Cancel a scheduled task on a remote node, using the ABONCW call 
Section 310 discusses remote task control. 
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2 

DECnet-RSX MACRO-1 1 Programming 

Facilities 



DECnet-RSX provides a library of MACRO-1 1 macros to use in network intertask 
communication. This chapter: 

■ Describes the three network macro formats. 

■ Explains the connect block and access options for your task. 

■ Lists the graphic conventions for this chapter. 

■ Describes each intertask communication macro call. 

2.1 RSX-1 1 Network Macro Formats 

You can use the following formats to code macros: 

■ BUILD type macro. Creates a parameter block at assembly time and is 
generally used in conjunction with an EXECUTE type macro or a DIR$ direc- 
tive. 

■ EXECUTE type macro. References the parameter block that a BUILD 
type macro created and executes the requested function. An EXECUTE type 
macro lets you override parameters that the BUILD type macro specified. 

■ STACK type macro. Creates a parameter block on the processor stack 
and executes the requested function. 

Section 2. 1 .4 has examples of these three macro format types. 



2-1 



2.1.1 BUILD Type Macros 

You use the BUILD type macro at assembly time. This macro creates a parameter 
block that contains arguments that describe the network function you requested. 
A pre-defined parameter block is especially useful for repetitions of the same net- 
work operation. If you omit an optional parameter from this block, the macro 
allocates space for it anyway. Later, you can use an EXECUTE type macro to fill in 
the argument. If you plan to use the EXECUTE type macro, however, you must 
include all of the BUILD type macro's trailing arguments. 

The format for a BUILD type macro is: 

label: xxx\^]% parameter- list[Jlag] 

where 

label is a symbolic name associated with the location of the parame- 

ter block. 

XXX is the name of a DECnet-RSX macro. 

[W] specifies that this network function will complete synchro- 

nously. The issuing task waits until the function completes 
before continuing. If you omit the W, the call completes asyn- 
chronously. 

parameter- list is a list of arguments that describe particular features of this 

call. Each parameter must be a valid argument for a .WORD or 
.BYTE MACRO- 11 directive. Each call description includes a 
list of the parameters for the call. The number of arguments 
specified must not exceed the number specified in an 
EXECUTE type macro that will use this parameter block. 

flag is a symbolic name that specifies an optional subfunction of the 

network macro. 

You can execute a BUILD type macro by issuing an EXECUTE type macro or a 
DIRS macro. A DIR$ macro call pushes the address of the network function 
parameter block that you created with the BUILD macro on the processor stack 
and then issues an EMT 377 for the Executive to execute the macro. You can write 
a DIR$ macro as follows: 

DIR$ adr,err 
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where 



adr is the address of the parameter block in the format of a source operand 

of an MOV instruction. 

err is the address of an optional error routine. The C-bit in the processor 

status word (PSW) is set whenever an error is encountered. 

A DIR$ macro generates less code than a corresponding EXECUTE macro. 

2.1 .2 EXECUTE Type Macros 

The EXECUTE type macro references a network function parameter block that 
you create at assembly time with a BUILD type macro. An EXECUTE type macro 
lets you enter parameters that override those that you originally defined with a 
BUILD macro. 

You must include all trailing arguments in a BUILD type macro that an EXECUTE 
type macro references. 

Once you redefine or specify new parameters for the call, the EXECUTE macro 
automatically executes the function that the call requests. The format for an 
EXECUTE type macro is: 

xvAr[ W] $ E label{ ,override-parameter-list\ [ JTag] 
where 

XXX is the name of a DECnet-RSX macro. 

[W] specifies that this network function will complete synchro- 

nously. The issuing task waits until the function completes 
before continuing. If you omit the W, the call completes asyn- 
chronously. 

label represents one of two values : 

■ The label of the BUILD type macro that supplies parame- 
ters for this EXECUTE macro. You can include arguments 
immediately following the label to override any parame- 
ters previously defined in the BUILD parameter block. 
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The label of an area of memory that will contain the 
parameters that you are currently specifying. The parame- 
ter block is built and the call is executed in the same macro. 



is a list of one or more arguments to replace parameters that 
you previously defined for this call in a BUILD type macro. 
Each argument in this list must be a valid source operand for an 
MOV S, label + offset MACRO- 1 1 instruction. 

You can override the value of a parameter and assign it a null 
value. For example, if an AST is not required, specify the 
parameter as 0. 

flag is a symbolic name that specifies an optional subfunction of the 

network macro. 

2.1.3 STACK Type Macros 

The STACK type macro creates the network function parameter block for the call 
on the processor stack and then executes the requested function. You must spec- 
ify all required parameters when you issue this macro or it will generate assembly 
errors. 

The format for a STACK type macro is: 
xx::xr[W]$S parameter-list[/lag] 
where 

XXX is the name of a DECnet-RSX macro. 

[W] specifies that this network function will complete synchro- 

nously. The issuing task waits until the function completes 
before continuing. If you omit the W, the call completes asyn- 
chronously. 

parameter-list is a list of arguments that describe particular features of this 
call. Each argument must have the form of a valid MACRO- 1 1 
MOV instruction source operand. Each call description 
includes a list of the parameters for the call. 

flag is a symbolic name that specifies an optional subfunction of the 

network macro. 



override- 
parameter-list 



2-4 



DECnet-RSX Programmer's Reference Manual 



2. 1 .4 Macro Format Examples 



The following examples demonstrate the three macro types. The first, a BUILD 
type macro, creates a parameter block for the call designated by xxx$ : 

label: xxx\^]% lun,efn, status, ast, < pl,p2, . . .,pn > 

The first example of an EXECUTE type macro references the parameter block cre- 
ated for label: 

xxx\Sf/]%Y. label 

The second EXECUTE type macro overrides the parameter list arguments pi and 
p2: 

xxx{^\$^ label, „„<pl,p2> 

The last example, a STACK type macro, creates a parameter block on the stack, 
and executes the call. 

jcxa:[W]$S #lun,#efn,#status,#ast, < #pl,#p2 > 

2.2 Connect Block Options 

As Chapter 1 described, a source task builds a connect block before issuing a con- 
nect request. This outgoing connect block contains information about the con- 
nect request's target node and task. It can also specify explicit access control 
information that gives the source task access to the target node. Before network 
software sends the connect block to the target task, it adds information about the 
source task or user. If you have an RSX-1 IM-PLUS or Micro/RSX system with 
outgoing proxy enabled, network software also adds proxy information (see 
Section 2.3). At the target node, the target task retrieves the incoming connect 
block from the network data queue. 

Your task can use either long or short connect blocks. Using long connect blocks 
lets your task support user IDs, passwords, and accounts of 39. characters each. 
Using short connect blocks lets your task support user IDs of up to 16. characters, 
passwords of up to 8. characters, and accounts of up to 16. characters. 

For greatest flexibility, use long connect blocks when writing a new task. How- 
ever, you can continue to use an existing task that uses short connect blocks with- 
out modifying the task. If you change an existing task to use long connect blocks, 
note the added buffer space requirements. Also note that if the task uses proxy 
access, you need not supply values for the access control information fields. 
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2.2.1 Using Connect Block Options 

The connect block size that you choose affects the following macro calls in your 



task: 

Macro Connect Block Option 

OPN$ Include the NT.LCB flag to specify a long connect block. 

CONBI $ Use CONB$ $ to build a short connect block. 

CONL$ $ Use CONL$ $ to build a long connect block. 

CON$ Provide the appropriate connect block length in the conblen argument. 

ACC$ Use the mail and mailen arguments to reference the appropriately- 

GND$ sized buffer. 

REJ$ 



When access verification for your task is on, your node's network software 
verifies access rights and removes the access control information before passing 
an incoming connect block to your task. For information on enabling verification 
for a task, refer to the DECnet-RSX Guide to Network Management Utilities. 

2.2.2 Receiving Connect Blocic Information 

You specify the type of connect block you want to receive by including or omit- 
ting the long connect block (NT.LCB) flag in the OPN$ (access the network) 
macro. If you specify the NT.LCB flag, network software uses long connect block 
fields when passing access control information to your task. 

In the GND$ macro, which retrieves the connect block from the network data 
queue, you specify a buffer to hold the incoming connect block information. The 
buffer size that you allocate may or may not equal the size of the incoming con- 
nect block, but in writing incoming data to your buffer, network software always 
uses the offsets appropriate to the connect block size that your OPN$ macro spec- 
ified. You receive all information if the source task sends the same size connect 
block that you receive, or if you receive long connect blocks and the source task 
sends a short connect block. However, if you receive short connect blocks and 
the source task sends a long connect block, you may lose some information. Net- 
work software writes the received information into the appropriate field if the 
information fits. Information that does not fit into the receiving field causes a data 
overrun error and is lost. 

You can choose to allocate a receiving buffer that is smaller or larger than the 
expected connect block. For example, you might allocate a smaller buffer to 
exclude all but the initial fields, or allocate a larger buffer to receive optional user 
data. The GND$ call description describes what happens when the task receives 
access control information that is smaller or larger than expected. 
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2.3 Access Control Information 



An outgoing connect request sends information to the target node in order to gain 
access to an account on the target node. You can specify the access control infor- 
mation and/or the network software can supply proxy information. Proxy access 
is available only with RSX-llM-PLUS or Micro/RSX. 

When you supply explicit access control information for the connect request, 
you specify a user ID, password, and, optionally, an account number. These iden- 
tify the target account on the remote node. You specify the explicit access control 
information as arguments to the macro that builds the connect block (CONB$$ or 
CONL$$). When the target system receives the connect request, it grants access 
according to what you specified. For information on which access control argu- 
ments the target system requires, refer to user documentation for that system; 
DECnet-RSX nodes require the user ID and password. For more information on 
explicit access control information, refer to the DECnet-RSX Network Manage- 
ment Concepts and Procedures manual. 

Proxy access, in contrast, eliminates the need to send passwords across the net- 
work. The network managers on both nodes must set up the environment for 
using proxy. Once your network manager enables outgoing proxy, your node 
automatically sends proxy information with all outgoing connect requests. Proxy 
information is the user ID under which the source task is executing. If incoming 
proxy is enabled on the target node, the system can grant access according to the 
proxy information and source node name. For information on how a target sys- 
tem verifies proxy access, refer to the DECnet-RSX Guide to Network Manage- 
ment Utilities. 

If an incoming connect request contains both explicit and proxy access control 
information, the target system uses the explicit information, and not the proxy 
information, to verify access. 
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2.4 Conventions Used in This Cliapter 

The following conventions are used in the macro descriptions and examples in 
this chapter: 

asterisk * flags arguments that you must check for information 

after the macro completes. For example, the status argu- 
ment specifies an array /data item where completion 
status information is stored when the macro completes. 

UPPERCASE indicates characters to type exactly as shown. You can 

type the text in upper- or lowercase. 

lowercase italic indicate variables for which you specify or the system 

supplies the actual values. 

square brackets [ ] enclose optional data. If the brackets enclose a vertical 
list of options, you can specify only one option. Do not 
type the brackets when you code a macro. 

Example: 

ABT[W]$ lun\efn\,[status\\ast\[, < out,outlen > ] 

In this macro, the lun argument is required; all other 
arguments are optional. 



braces { } enclose options, from which you must choose one and 

only one. Do not type the braces when you code the 
macro. 

Example: 

GND[ W] $ lun , {efn] , [status] , [ast] , 

mail, mien > 
J <mail,mlen,mask> , NT. TYF \ 
I ,NT.LON [ 
^<,, mask >,NTLON ^ 

In this example, you must include one of the four argu- 
ment strings enclosed within the braces when you code 
GND$. 
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commas and must be typed as part of the macro format. Even if you 

angle brackets < > omit an argument, include the comma that delineates its 
field unless no other arguments follow. 

Example: 

Basic format: 

ABT[W]$ lun,[efn],[status],[ast][, < out,outlen > ] 
Sample macro: 
ABT$ status 

efn, ast, out, and outlen have been omitted. A comma 
delineates the field for the missing efn argument; no 
commas are necessary for the three arguments dropped 
at the end of the macro. 

numbers are octal unless followed by a decimal point. If the 

assembler default radix has been set to octal, you can 
designate a decimal radix by placing a decimal point 
immediately after a number. 

Example: 

SND$S #3,#1,#I0STN,,<#MAUX,#16.> 

In this example, 16 is a decimal number. 
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2.5 Intertask Communication Macros 



This section contains descriptions and usage guidelines for the intertask commu- 
nication calls that Table 2-1 lists. Read the preceding material in this chapter 
before using the calls. If you are unfamiliar with intertask communication con- 
cepts, also read Chapter 1 carefully. 



Table 2-1 ■ 


IIILd laoiV wwl 1 III lUI llwCILlVlll IVICIVl w9 


Macro 


Function 


ABT$ 


Abort a logical link 


ACC$ 


Accept a logical link connect requrest 


CLS$ 


End a task's network operations 


CON$ 


Request a logical link connection 


CONB$$ 


Build a short connect block for CON$ macro 


CONL$$ 


Build a long connection block for CON$ macro 


DSC$ 


Disconnect a logical link 


GLN$ 


Get local node information 


GND$ 


Get data from network data queue 


OPN$ 


Access the network 


REC$ 


Receive data over a logical link 


REJ$ 


Reject logical link connect request 


SND$ 


Send data over a logical link 


SPA$ 


Specify a user AST routine 


XMI$ 


Send interrupt message over a logical link 



2.5.1 Common Argument Definitions 

This section defines commonly-used arguments for intertask communication 
macros. 

■ label 

has the following meanings, depending on the macro type: 

BUILD type: label is a symbolic name associated with the location of 

the argument block. 
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EXECUTE type: label can represent one of two values: 

The label of the BUILD macro that supplies arguments for the current 
EXECUTE macro. You can override any arguments that the BUILD macro 
defines by reentering them after label in the EXECUTE macro. 

The label of an area of memory that will contain the arguments that you 
specify in the current EXECUTE macro. 

■ status 

unless noted otherwise, is the address of an optional 2 -word status block 
that contains completion status information on return from the macro. If 
specified, this block will contain the following values when the macro com- 
pletes: 

Word 0: Byte = Error/completion code 

Byte 1 = 
Word 1: 

Each macro description lists the error/completion codes for that macro. 

■ out,outlen 

define optional user data to send with certain macros. These are optional 
arguments, but are always paired; use both or omit both. 

out is the octal starting address of a buffer that contains optional user 

data you can send on some operations. 

outlen is the length in decimal bytes of the 1- to 16. -byte message to 
send. 
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ABT$ 

(Abort a Logical Link) 

2.5.2 ABT$ — Abort a Logical Link 

Use: 

Issue ABT$ from either task to abort a logical link. ABT$ immediately aborts all 
pending transmits and receives, disconnects the link, and frees the LUN assigned 
to the logical link. When you issue ABT$, you can send 1 to 16. bytes of user data 
to the task from which you are disconnecting (see the out,outlen arguments). 

Formats: 

label: ABT[W] $ lun,[efn] , [status] , [ast][, < out,outlen > ] 

ABT[W]$E label,[lun],[efn],[status],[ast][, < out,outlen > ] 

ABT[W]$S lun,[efn],[status],[ast][, < out,outlen > ] 



Arguments: 

label 

specifies the location of the argument block. See the definition in Section 
2.5.1. 

lun 

identifies the logical link to abort. If you initiated the connection, enter the 
LUN you used in the CON$ macro. If you accepted the connection, enter the 
LUN you used in the ACC$ macro. 

* efn 

specifies an optional event flag number to set when ABT$ completes. 

* status 

specifies completion status information on return from ABT$ . See the defini- 
tion in Section 2.5.1. 
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ast 

is the address of an optional user-written AST routine to execute after ABT$ 
completes. 

out,outlen 

define optional user data to send. See the definition in Section 2.51. 



Error/Completion Codes: 



IS. sue 



The macro completed successfully. 



lE.ABO 



The specified logical link has already been aborted or discon- 
nected. 



IE. BAD 



The optional user data exceeds 16. bytes. 



lE.IFC 



LUN not assigned to NS: . 



lE.NLN 



No logical link has been established on the specified LUN. 



lE.NNT 



The issuing task is not a network task; OPN$ did not execute suc- 
cessfully. 



lE.SPC 



Invalid buffer argument; the optional user data buffer {out) is out- 
side the user task address space. 
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ACC$ 

(Accept Logical Link Connect Request) 
2.5.3 ACC$ — Accept Logical Link Connect Request 



Use: 



Issue ACC$ from the target task to establish a logical link with the source task. 
When you issue ACC$, you can send 1 to 16. bytes of user data to the source task 
(see the out,outlen arguments). 

Formats: 

label: ACC[W]$ lun\efn]\status\,{asf\,<mail\mailen\, 

[out,outlen] > [,NOFLOW] 

ACC[ W] $ E label, [lun] , [efn] , [status] , [ast] , < [mail] , [mailen] , 

[out,outlen] > [,NOFLOW] 

ACC[W]$S lun,[efn],[status],[ast], < mail, [mailen], 

[out,outlen] > [,NOFLOW] 

Arguments: 

label 

specifies the location of the argument block. See the definition in Section 
2.5.1. 

lun 

assigns the logical link number. Use this LUN to refer to this logical link in 
any subsequent REC$, SND$, XMI$, ABT$, or DSC$ macro. 

* efn 

specifies an optional event flag number to set when ACC$ completes. 



* status 

specifies completion status information on return from ACC$. See the defini- 
tion in Section 2.5.1. 
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ast 

is the address of an optional user- written AST routine execute after ACC$ 
completes. 

mail 

is the address of the connect block sent by the source task and retrieved by 
GND$. Specify the same address for this and the GND$ mail argument. The 
connect block information is required to establish the connection. 

mailen 

is the length of the connect block in decimal bytes. The default value is 98. 
bytes (N.CBL), the short connect block length, not including optional data. 
For a long connect block, specify 178. bytes (M.CBL), the long connect block 
length, not including optional data. 

out,outlen 

define optional user data to send. See the definition in Section 2.5. 1. 



Flag: 



NOFLOW 



disables flow^ control for incoming messages addressed to the task that issued 
ACC$. Omitting NOFLOW establishes flow control for incoming messages. You 
can enable or disable flow control independently at either end of the link. Use the 
NOFLOW option with caution (see Section 1.2.12). 



Error/Completion Codes: 

IS . sue The macro completed successfully . 

IE. ABO The task that requested the connection has aborted or requested 

a disconnect before the connection could complete. 

lE.ALN A logical link has already been established on the specified LUN. 

IE. BAD Either the temporary link address in the connect block sent by 

the source task is invalid, or the optional user data buffer length 
(outlen) exceeds 16. bytes. 

lE.IFC LUN not assigned to NS: . 
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lE.NNT The issuing task is not a network task; OPN$ did not execute suc- 

cessfully. 

lE.RSU System resources needed for the logical link are not available. 

IE . SPC Invalid buffer argument; either the pending connect block (mail) 

or the optional user data buffer (put) is not word aligned, or one 
of them is outside the user task address space. 
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CLS$ 

CLS$ 

(End Task Network Operations) 

2.5.4 CLS$ — End Task Network Operations 

Use: 

Issue CLSI from either task to end that task's network activity, abort its logical 
links, and free its network LUNs. If the CLS$ call occurs when data remains in the 
task's network data queue, network software: 

■ Reschedules the task if pending connect requests arrived while the task was 
active. The task receives these connect requests when it restarts. There is a 
limit of one retry and a timeout period of approximately 1 5 seconds. 

■ Rejects connect requests that arrived while the task was inactive. 

■ Discards interrupt, user disconnect, user abort, or network abort messages. 

Formats: 

label: CLS[W]$ [lun\\efn\\status\[,ast\ 

CLS[W] $E label, [lun] , [efn] , [status][,ast] 

CLS[W] $S [lun] , [efn] , [status][,ast] 

Arguments: 

label 

specifies the location of the argument block. See the definition in Section 
2.5.1. 

lun 

identifies the logical unit number of the network data queue. Use the same 
LUN you assigned in the OPN$ macro. 

* efn 

specifies an optional event flag number to set when CLS$ completes. 
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* status 

specifies completion status information on return from CLS$. See the defini- 
tion in Section 2.51. 

ast 

is the address of an optional user-written AST routine to execute after CLS$ 
completes. 

Error/Completion Codes: 

IS . sue The macro completed successfully . 

lE.IFC LUN not assigned to NS: . 

lE.NNT The issuing task is not a network task; OPN$ did not execute suc- 

cessfully. 

lE.PRI The network is not accessed on the specified LUN. 
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CON$ 

(Request Logical Link Connection) 

2.5.5 CON$ — Request Logical Link Connection 

Use: 

Issue CON$ from the source task to request a logical link with the target task. 
Before issuing CON$, you must build a connect block (see Section 2.5.6 or 2.5 7) 
that CON$ can pass to the target node. 

When a remote system receives a connect request, it checks the remote task. If the 
task is currently installed and inactive, the system automatically loads and acti- 
vates it. The target task must issue a GND$ macro call to retrieve the connect 
block information. The task evaluates the connect request and either accepts or 
rejects it. 

You can send 1 to 16. bytes of user data to the target task and/or receive 1 to 16. 
bytes of user data from the target task when it accepts/rejects your connect 
request. 

Formats: 

label: CON[W]$ lun,[efn],[status],[ast], < conbl,[conblen], 

[out,outlen],[inJnlen] > [,NOFLOW] 

CON[W]$E label,[lun],[efn],[status],[ast], < conbl,[conblen], 

[out,outlen],[mJnlen] > [,NOFLOW] 

CON[W]$S lun,[efn],[status],[ast], < conbl,[conblen], 

[out,outlen],[in,tnlen] > [,NOFLOW] 

Arguments: 

label 

specifies the location of the argument block. See the definition in Section 
2.5.1. 
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lun 

assigns the logical link number. Use this LUN to refer to this logical link in 
any subsequent REC$, SND$, XMI$, ABT$, or DSC$ macro. 

* efn 

specifies an optional event flag number to set when CON$ completes. 

* status 

is the address of an optional 2 -word status block that contains completion 
status information on return from CON$. If specified, this block will contain 
the following values when CON$ completes: 

Word 0: Byte = Error /completion code (see the list that follows) 

Byte 1=0 

Word 1 : Byte = Contents depend on error completion code in word 0, 
byte (see the list that follows) 

Byte 1=0 

This list shows the error /completion codes that you can receive in word 0, 
byte and the corresponding contents of word 1, byte 0: 



Error/Completion Code 
Word 0, Byte 

IS. sue 

Connection accepted 
IS.DAO 

Connection accepted with data overrun 
lE.DAO 

Connection rejected by user with data overrun 
lE.URJ 

Connection rejected by user 
lE.NRJ 

Connection rejected by DECnet 



Word 1, Byte 

Received byte count 
(0 if no data is received) 

Received byte count 
(0 if no data is received) 

Received byte count 
(0 if no data is received) 

Received byte count 
(0 if no data is received) 

Reason for rejection 
(refer to Appendix A) 



All other cases 
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ast 

is the address of an optional user-written AST routine to execute after CON$ 
completes. 

conbl 

is the address of the connect block built using CONL$$ or CONB$$. This 
block must start on an even byte (word) boundary. 

conblen 

is the length of the connect block in decimal bytes. If you omit this value, the 
CONS macro uses the short connect block length, 72. bytes (N.RQL). To use 
a long connect block, specify the long connect block length, 1 52. (M.RQL). 

out,outlen 

define optional user data to send. See the definition in Section 2.5.1. 
in^inlen 

define the buffer to receive optional user data from the target task. These are 
paired optional arguments; use both or omit both. If you omit these argu- 
ments and the target task sends user data, a data overrun status code (IS.DAO 
or lE.DAO) will be returned. 

* in is the octal address of the buffer. 

inlen is the buffer length in decimal bytes (1 to 16.). 

Flag: 

NOFLOW 

disables flow control for this end of the link. Omitting NOFLOW establishes flow 
control at this end of the link. You can choose to enable or disable flow control 
independently at each end of the link. Use the NOFLOW option with caution (see 
Section 1.2.12). 
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Error/Completion Codes: 

IS . sue The macro completed successfully . 

IS.DAO The macro completed successfully; the target task accepted the 

connection. However, the target task sent back some optional 
user data when it accepted the connect request, which was lost. 

lE.ALN A logical link has already been established on the specified LUN. 

IE. BAD Either the optional user data buffer exceeds 16. bytes, or the field 

length count in the connect block is too large. 

lE.DAO The connection was rejected and some optional user data sent 

from the target task when it rejected your connect request was 
lost. 

IE . IPC LUN not assigned to NS : . 

lE.NNT The issuing task is not a network task; OPN$ did not execute suc- 

cessfully. 

lE.NRJ The network rejected the connection (see the reject reason codes 

in Appendix A). 

lE.PRI The local node is shutting down. No logical link can be estab- 

lished. 

lE.RSU System resources needed for the logical link are not available. 

lE.SPC Invalid buffer argument; either the connect block {conbl) is not 

word aligned, or the optional user data buffers {in or out) are out- 
side the user task address space. 



lE.URJ 



The remote user task rejected the connection. 
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CONB$$ 

(Build Connect Block (Short)) 

2.5.6 CONB$$ — Build Connect Block (Short) 

Use: 

Issue CONB$ $ from the source task to build a 72. -byte connect block. The CONS 
macro call passes this outgoing connect block to the target task. The connect 
block contains the target node name, destination descriptor, and, optionally, 
explicit access control information. The target task can use this information to 
determine whether to accept (ACC$) or reject (REJ$) the connect request. 

To include explicit access control information, include the rqid, pass, and, 
optionally, accno arguments in the macro. You can omit the explicit access con- 
trol information if you already included it in an alias node name or if you use 
proxy access. The target system verifies access control information according to 
its system conventions. If the target node uses and has enabled access verifica- 
tion, it performs verification before passing the connect request to the target task. 

For more information on access control verification, refer to the DECnet-RSX 
Network Management Concepts and Procedures manual. For more information 
on aliases, refer to the DECnet-RSX Guide to User Utilities or the DECnet-RSX 
Network Management Concepts and Procedures manual. For more information 
on proxy access, refer to the DECnet-RSX Guide to Network Management Utili- 
ties. 

Format: 

CONB$$ {node]\obf\,\fmt, < descrip >\\rqid\\ < pass>\[,accn6\ 

Arguments: 

node 

is the name of the target node. The name must have 1 to 6 alphanumeric charac- 
ters, including at least 1 alphabetic character. 

The obj, fmt, and descrip arguments comprise the destination descriptor. You 
must specify this information in order to access the task. 
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obj 

is the target task's object type. The object type for a named object is 0. The object 
type for a numbered object is in the range 1 to 127. for a DECnet task or 128. to 
255. for a user task. Refer to Appendix B for a list of object type codes. 

Privileged users can define their own object types; for information, refer to the 
DECnet-RSX Network Management Concepts and Procedures manual. 

fmt 

is the descriptor format type. To connect to a named object, specify for the 
descriptor format type and specify the descrip argument. To connect to a num- 
bered object, specify 1 and omit the descrip argument. 

descrip 

is the target task name (1 to 16. ASCII characters). Specify this argument only if 
you specified for the/m^ argument. 

The rqid, pass, and accno arguments comprise explicit access control informa- 
tion that specifies an account on the remote node. 

rqid 

is the user ID (1 to 16. ASCII characters). 
pass 

is a 1 to 8. -byte password. To enter an ASCII (as opposed to binary) password, 
precede each character of the password with an apostrophe (') and separate the 
characters with commas. For example, enter the password PAS as 'P,'A,'S. 

accno 

is your account number at the remote node or process (1 to 16. ASCII characters). 

NOTE 

During task execution, you can dynamically supply 
or modify values for the connect block fields, using 
the offsets in Table 2-2. You must use this method to 
supply non-ASCII data for a field that normally 
requires ASCII data. 

You can also choose not to issue CONB$$ and 
instead allocate a 72. byte block of storage. Issue the 
CRBDF$ call to define the offsets, with which you 
fill in the connect block. 
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Remember that a successful connect request requires 
that the connect block contain certain fields, 
whether you enter the values as arguments to the 
CONB$$ macro or dynamically during task execu- 
tion. 



Connect Block: 

Table 2-2 describes the connect block's symbolic offsets. Figure 2-1 is an exam- 
ple of a 7 2. -byte connect block. 

Table 2-2: CONB$$ Connect Block Symbolic Offsets 



Symbolic 



Length 



Offset 


in Bytes 


Contents 






DESTINATION DESCRIPTOR 


N.RND* 


6. 


Remote node name with trailing blanks 


N.RFM 


1. 


Destination descriptor format type: or 1 


N.ROT 


1. 


Destination object type: 0-255. 



N.RIDC* 

N.RID* 

N.RPSC* 

N.RPS* 

N.RACC* 

N.RAC* 

N.RQL = 72. 



2. 

16. 

2. 

8. 

2. 

16. 



Descriptor Field for Format 
18. Not used 

Descriptor Fields for Format 1 

N.RDEC* 2. Destination task name length (equal to or 
less than 16. bytes) 

N.RDE* 16. Destination task name 

ACCESS CONTROL INFORMATION 

User ID length (equal to or less than 16. bytes) 
User ID 

Password length (equal to or less than 8. bytes) 
Password 

Account number length (equal to or less than 16. bytes) 
Account number 



These symbolic offsets are guaranteed to be even (word aligned). 
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Figure 2-1 illustrates the connect block that the following call builds: 

CONB$$ TACOMA , , 1 , <RECVR> , BLOGGS , < • P , ' A , • S> 

The connect block contains the following values: 



Field 

Destination node 
Object type 
Descriptor format type 
Destination task name length 
Destination task name 
User ID length 
User ID 

Password length 
Password 



Value 

TACOMA, an RSX node 

(named object) 

1 

5 

RECVR 
6 

BLOGGS 
3 

PAS 



The account number length and account number are omitted because RSX target 
systems do not require them. 

The call supplies explicit access control information. It could omit that informa- 
tion when an alias node name contains the user ID and password, or to use proxy 
access. The access control fields in the figure would then be empty. The offsets 
are in octal notation. 
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Figure 2-1 : Outgoing CONB$$ Connect Blocic 
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CONL$$ 

(Build Connect Block (Long)) 

2.5.7 CONL$$ — Build Connect Block (Long) 

Use: 

Issue CONL$$ from the source task to build a 152. -byte connect block. The CON 5? 
macro call passes this outgoing connect block to the target task. The connect 
block contains the node name, destination descriptor, and, optionally, explicit 
access control information. The target task can use this information to determine 
whether to accept (ACC$) or reject (REJ$) the connect request. 

To specify explicit access control information, you call the following associated 
macros: 

■ CNID$ $ lets you specify a user ID 

■ CNPS$ $ lets you specify a password 

■ CNAC $ $ lets you specify an account number 

To omit one or more of the access control fields, simply omit calling the macro. 
You need not issue a separate .MCALL directive for each; the .MCALL directive 
for CONL$$ calls CONL$$ and the three associated macros. You can omit the 
access control information if you already included it in an alias node name or if 
you use proxy access. The target system verifies access control information 
according to its system conventions. If the target node uses and has enabled 
access verification, it performs verification before passing the connect request to 
the target task. 

For more information on access control verification, refer to the DECnet-RSX 
Network Management Concepts and Procedures manual. For more information 
on aliases, refer to the DECnet-RSX Guide to User Utilities or the DECnet-RSX 
Network Management Concepts and Procedures manual. For more information 
on proxy access, refer to the DECnet-RSX Guide to Network Management Utili- 
ties. 



2-28 



DECnet-RSX Programmer's Reference Manual 



CONL$$ 



Format: 



CONL$$ 


[node] , [obj] , [fmt, < descrip > ] 


CNID$$ 


[rqid] 


CNPS$$ 


[<pass>] 


CNAC$$ 


[accno] 



Arguments for CONL$$: 

node 

is the name of the target node. The name must have 1 to 6 alphanumeric charac- 
ters, including at least 1 alphabetic character. 

The obj, fmt, and descrip arguments comprise the destination descriptor. You 
must specify this information in order to access the target task. 

obj 

is the target task's object type. The object type for a named object is 0. The object 
type for a numbered object is in the range of 1 to 127. for a DECnet task or 128. to 
255 . for a user task. Refer to Appendix B for a list of object type codes. 

Privileged users can define their own object types; for information, refer to the 
DECnet-RSX Network Management Concepts and Procedures manual. 

fmt 

is the descriptor format type. To connect to a named object, specify for the 
descriptor format type and specify the descrip argument. To connect to a num- 
bered object, specify 1 and omit the descrip argument. 

descrip 

is the target task name (1 to 16. ASCII characters). Specify this argument only if 
you specified for the fmt argument. 
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Argument for CNID$$: 

rqid 

is the user ID (1 to 39. ASCII characters). 

Argument for CNPS$$: 

pass 

is a 1 to 39. -byte password. To enter an ASCII (as opposed to binary) password, 
precede each character of the password with an apostrophe (') and separate the 
characters with commas. For example, enter the password RADIO as 
'R,'A,'D,T,'0. 

Argument for CNAC$$: 

accno 

is your account number at the remote node or process (1 to 39. ASCII characters). 

NOTE 

You can choose to create the entire connect block or 
specify any of the CONL$$, CNID$$, CNPS$$, or 
CNAC$$ arguments dynamically during task execu- 
tion. In addition, to specify non-ASCII data for an 
argument that normally requires ASCII data, you 
must do so dynamically. You can also modify any 
connect block field this way. 

To create the connect block dynamically, reserve a 
152. -byte block of storage, which equals the M.RQL 
length (see Table 2-3); to specify any connect block 
field dynamically, leave the argument blank in the 
macro call. Issue the CRBDF$ call to define the con- 
nect block symbolic offsets listed in Table 2-3. Dur- 
ing task execution, use these offsets to specify or 
modify the connect block information. 

A successful connect request (CONS) requires all of 
the necessary connect block fields, whether you put 
them in the macro arguments or enter them dynami- 
cally during task execution. 
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Connect Block: 

Table 2-3 lists the connect block symbolic offsets. Figure 2-2 illustrates a sample 
connect block. 

Table 2-3: CONL$$ Connect Block Symbolic Offsets 



Symbolic 
Offset 



Length 
In Bytes 



Contents 



M.RND^ 

M.RFM 

M.ROT 



M.RIDC* 
M.RID* 

M.RPSC* 
M.RPS* 

M.RACC* 
M.RAC* 

M.RQL= 152. 



2. 
39. 

1. 

2. 
39. 

1. 

2. 
39. 

1. 



DESTINATION DESCRIPTOR 

Remote node name with trailing blanks 
Destination descriptor format type: or 1 
Destination object type.- 0-255. 
Descriptor Field for Format 
18. Not used 

Descriptor Fields for Format 1 

M.RDEC* 2. Destination task name length 
(equal to or less than 16. bytes) 

M.RDE* 16. Destination task name 

EXPLICIT ACCESS CONTROL INFORMATION 

User ID length (equal to or less than 39. bytes) 
User ID 
Not used 

Password length (equal to or less than 39. bytes) 

Password 

Not used 

Account number length (equal to or less than 39. bytes) 
Account number 
Not used 



These symbolic offsets are guaranteed to be even (word aligned). 
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Figure 2-2 illustrates the connect block that the following call builds: 



CONL$$ GR0T0N,0,1,<RECEIVER> 
CNID$$ EDGAR 

CNPS$$ <'R, 'A, 'D, 'I, '0, 'S, 'T, 'A, 'T, 'I, '0, 'N> 
CNAC$$ 

The connect block contains the following values: 



Field 

Destination node 

Object type 

Descriptor format type 

Destination task name lengtli 

Task name 

User ID length 

User ID 

Password length 
Password 



Value 

GROTON, an RSX node 
(named object) 
1 
8 

RECEIVER 
5 

EDGAR 
12 

RADIOSTATION 



The account number length and account number are omitted because RSX target 
systems do not require account numbers. 

The call supplies explicit access control information. If, instead, you have defined 
the access control information in an alias node name, or if you use proxy, the 
access control information fields in the figure would be empty. The offsets are in 
octal notation. 
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Figure 2-2: Outgoing CONL$$ Connect Block 
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DSC$ 

(Disconnect a Logical Linic) 

2.5.8 DSC$ — Disconnect a Logical Link 
Use: 

Issue DSC$ from either task to disconnect the logical link and free the logical unit 
number. Unlike ABT$ (Section 2.5.2), DSC$ causes all pending transmits to com- 
plete before disconnecting the link. While these transmits are completing, the 
task continues to receive messages. When the last transmit has completed, each 
pending receive is aborted with an IE. ABO status code in the I/O status block. 
With DSC$, you can send 1 to 16. bytes of user data to the task from which you 
are disconnecting (see the out,outlen arguments). 

Formats: 

label: DSC[W]$ lun,[efn],[status],[ast][, < out,outlen > ] 

DSC [W] $ E label, [lun] , [efn] , [status] , [ast][, < out,outlen > ] 

DSC [ W] $ S lun, [efn] , [status] , [ast] [,<out, outlen > ] 

Arguments: 

label 

specifies the location of the argument block. See the definition in Section 
2.5.1. 

lun 

identifies the logical link to disconnect. If you initiated the connection, 
enter the LUN you used in the CON$ macro. If you accepted the connection, 
enter the LUN you used in the ACCS macro. 

* efn 

specifies an optional event flag number to set when DSC$ completes. 

* status 

specifies completion status information on return from DSC$ . See the defini- 
tion in Section 2.5.1. 
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ast 

is the address of an optional user- written AST routine to execute after DSC$ 
completes. 

out,outlen 

define optional user data to send. See the definition in Section 2.5.1. 
Error/Completion Codes: 



lo. 




1 nc macro compicieci successiuny . 


IE 


ABO 


The specified logical link has already been aborted or discon- 
nected. 


IE 


BAD 


The optional user data exceeds 16. bytes. 


IE 


IPC 


LUN not assigned to NS:. 


IE 


,NLN 


No logical link has been established on the specified LUN. 


IE 


.NNT 


The issuing task is not a network task; OPN$ did not execute suc- 
cessfully. 


IE 


PRI 


The network is not accessed on the specified LUN. 


IE 


SPC 


Invalid buffer argument; the optional user data buffer (put) is out- 



side the user task address space. 



DECnet-RSX MACRO-1 1 Programming Facilities 



2-35 



GLN$ 



GLN$ 

(Get Local Node Information) 

2.5.9 GLN$ — Get Local Node Information 

Use: 

Issue GLN$ from either task to place the name and default NSP segment size of the 
local node in a specified buffer. 

Getting the local node name can be helpful if two tasks on the same node use the 
network interface to communicate. Each task can issue GLN$ and use the 
returned local node name as the destination in a connect request. A task that dis- 
plays the local node name can also use GLN$ . 

The default NSP segment size tells you how NSP segments data transmitted on a 
logical link. By knowing the default NSP segment size, you can adjust the length 
of message blocks to transmit for most efficient use of transmit buffers (large data 
buffers). 

Formats: 

label: GLN[ W] $ [lun\ , [efn] , [status] , [ast] ,<buf, buflen > 

GLN[W]$E label,[lun],[efn],[status],[ast], < buf, buflen > 

GLN[W]$S [lun],[efn],[status],[ast], < buf, buflen > 

Arguments: 

label 

specifies the location of the argument block. See the definition in Section 
2.5.1. 

* efn 

specifies an optional event flag number to set when GLN$ completes. 
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status 

is the address of an optional 2 -word status block that contains completion 
status information on return from GLN$ . If status is specified, the contents 
of word 1 depend on the error /completion code returned in word 0, byte 
(word 0, byte 1 is always 0). 

Contents in Word 0, Byte Contents of Word 1 

IS . sue ( 1 ) or IE . DAO (-13) Number of bytes transferred to the user 

buffer 

l^.xxx (excluding IE. DAO, 
:xrxv refers to lE.NNT, 
lE.PRI, IE. SPG) 

ast 

is the address of an optional user-written AST routine to execute after GLN$ 
completes. 

buf 

is the address of the buffer to contain the received data. This buffer must 
start on an even byte (word) boundary. 

buflen 

is the length of the buffer to contain the received data. The buffer length 
determines the data returned, as follows. 

Length Returned Data 

6 bytes Local node name, left justified and in ASCII. Names with fewer 

than 6 bytes are padded with spaces. 

8 bytes Local node name, default NSP segment size. 

10 bytes Local node name, default NSP segment size, node number. 

The first six bytes contain the local node name. The next two bytes contain 
the default segment size. The last two bytes contain the local node number 
in the lower 10 bits and the local area number in the higher 6 bits. 
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Error/Completion Codes: 

IS . sue The macro completed successfully . 

lE.DAO Data overrun. The network data was longer than the specified 

buffer. As much data as fits into the buffer is transferred to it; any 
remaining data is lost. 

lE.IFC LUN not assigned to NS: . 

lE.NNT The issuing task is not a network task; OPN$ did not execute suc- 

cessfully. 

lE.PRI The network is not accessed on the specified LUN. 

lE.SPC Invalid buffer argument; the buffer specified to receive network 

data {buf) is outside the user task address space. 
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GND$ 

(Get Network Data) 



2.5.10 GND$ — Get Network Data 



Use: 



Issue GND$ from either task to get data from that task's network data queue and 
store it in a mail buffer. You specify the buffer in the mail and mien parameters. 
The status block identifies what type of message the call retrieved. The status 
block identifies one of the following unsolicited message types in word 0, byte 1 : 



You can use the SPA$ macro (Section 2.5.15) to get a count of data items in the 
network data queue. If the queue is empty, GND$ completes with an error 
(lE.NDA), even if you use the GND[W] form. 

If GND$ retrieves a connect request, it writes the accompanying connect block 
information to the mail buffer. You can use a long or short connect block, 
depending on the length of the user IDs, passwords, and accounts you expect to 
receive. For information about the incoming connect block, see the "Connect 
Block" section of this call description. 



Connect request 
Interrupt message 



NT.CON 
NT.INT 
NT.DSC 
NT.ABT 
NT. ABO 



User disconnect notice 
User abort notice 
Network abort notice 



Formats: 



label: GND[W]$ [lun],{efn\\status\\ast] 




< mail,mlen > 

< mail,mlen,mask> , NT. TYP 



J 
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GND[W] $ E label, [lun] , [efn] , [status] , [ast] , 

< mail,mlen > ^ 

< mail, mien, mask >, NT. TYP I 
,NT.LON I 
<„mask> , NT. LON J 

GND[W] $ S [lun] , [efn] , [status] , [ast] , 

^< mail,mlen > ^ 
J <mail, mien, mask> , NT. TYP\ 
] .NT.LON I 
^< „mask> , NT .\.ON 

Arguments: 

label 

specifies the location of the argument block. See the definition in Section 
2.5.1. 

lun 

identifies the logical unit number assigned to the network data queue. Use 
the LUN that you specified in OPN$ . 

* efn 

specifies an optional event flag number to set when GND$ completes. 

* status 

is the address of an optional 2-word status block that contains completion 
status information on return from GND$. Refer to Table 2-4 for a summary 
of the status block contents after GND$. 

ast 

is the address of an optional user-written AST routine to execute after GND$ 
completes. 
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mail, mien 

define the task mail buffer to receive the network data or connect block on 
return from GND$. You must specify these arguments unless you use the 
NT.TYP and NT.LON flags. Refer to Table 2-5 for a list of the short connect 
block contents and to Table 2-6 for a list of the long connect block contents. 

* mail 

is the octal address of the buffer, which must start on an even byte (word) 
boundary. 

mien 

is the length of the buffer in decimal bytes. The incoming data is written to 
the buffer according to the offsets of the connect block type that you speci- 
fied in the OPN$ call. 

You can allocate a mail buffer that is equal to, smaller than, or larger than the 
expected connect block and optional data. To receive an entire connect 
block, allocate space according to the connect block type that you specified 
in the OPN$ macro call: 

Short connect block 98. bytes (N.CBL) 

Long connect block 178. bytes (M.CBL) 

You can add space for optional data: 

Optional data Up to 16. bytes 

Optional data length field 2 . bytes 

Network software writes the retrieved information to the buffer field by 
field, according to the offsets of the specified connect block type. If the mail 
buffer and the incoming connect block are different sizes, the following 
results occur. 
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Mail Buffer Size 



Result 



You allocate a buffer that is larger 
than the incoming connect block. 

You allocate a buffer that is smaller 
than a full connect block. 



You allocate a buffer for receiving a 
short connect block and instead 
receive a long connect block. 



No error occurs. 

Connect block data is written field by 
field into the buffer until no more fits. A 
data overrun (IS.DAO) completion status 
results, even if all the received data fits 
into the buffer. 

If the incoming data fits according to the 
short connect block offsets, you get all 
the data, but a data overrun (IS.DAO) 
completion status results. 

If the data in any incoming field exceeds 
the size of the analogous receiving field, 
the data in that field is lost. The length 
value for the field becomes 0, and a data 
overrun (IS.DAO) completion status 
results. 



mask 



specifies the data type to select from the network data queue. Normally, 
GND$ returns items from the network data queue on a first-in, first-out 
basis. However, mask lets you select the first item on the queue that matches 
a specific message type and/or LUN. Enter one of the following combina- 
tions for the mask argument. 



Message Type 
(Byte 0) 

NT. CON (connect request) 

NT. INT (interrupt) 

NT. DSC (user disconnect) 

NT.ABT (user abort) 

NT. ABO (network abort) 

(Selects any message 
type on the specified LUN). 



Logical Unit Number 
(Byte1) 

(Selects the first LUN of message type NT. CON) 

or LUN 

or LUN 

or LUN 

or LUN 

LUN 
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For example, to select the first disconnect message (NT. DSC) on LUN 3 from 
the network data queue, code the mask argument as 3 * 256. + NT. DSC. 

Specifying in byte 1 returns the first message of the type specified in byte 
0, regardless of LUN. 

Flags: 

NT.TYP 

indicates a mask argument requesting a specific message type and/or LUN. 
Always use NT.TYP when specifying mask with mail and mien. 

If you use NT.TYP in a BUILD type GND$, you must also use it in any subsequent 
EXECUTE type GND$. 

NT.LON 

supports dynamic assignment of mail buffer space. Specifying NT.LON with 
GND$ returns information about the first message in the network data queue 
without removing the message from the queue or placing it in the mail buffer. 
With NT.LON, the status block returns the message type in word 0, byte 1 and the 
message length in word 1, byte 0. You cannot use mail, mien, and NT.TYP with 
NT.LON. 

If you use NT.LON in a BUILD type GND$ , you must also use it in any subsequent 
EXECUTE type GND$. 
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Table 2-4: Status Block Contents After GND$ 

( 

If GND$ completes successfully with NT.LON omitted: 



Status Word 


Status Word 1 




ByteO 


Byte1 


ByteO 


Bytel 


issue 

or 

IS.DAO 
or 

TF DAD 


NT.eON 
Connect 
request 


Number of bytes in 
connect block. 


Access verification (1) and 

privileged code: 

VS.NPV = Requesting user is 

nonprivileged. 

VS.PRV = Requesting user is 

privileged. 

VZ.NVD = Verification was 
not done. (2) 

VE.FAI = Verification failed. 
(3) 


issue 

or 

lE.DAO 


NT.INT 

Interrupt 

message 


Number of bytes 
(1-16) in optional 
message. If 0, no 
message was received. 


LUN over which the inter- 
rupt message was received. 




NT.DSe 
User 

disconnect 


Number of bytes 
(1-16) in optional 
message. If 0, no 
message was received. 


LUN over which the user dis- 
connect message was 
received. 




NT.ABT 

User 

abort 


Number of bytes 
(1-16) in optional 
message. If 0, no 
message was received. 


LUN over which the network 
abort message was received. 


IS. sue 

or 

lE.DAO 


NT. ABO 
Network 
abort 


Reason for network 
abort (See codes in 
Appendix A). 


LUN over which the notice 
was received. 


If GND$ completes successfully with NT.LON specified: 




Status Word 


Status Word 1 




ByteO 


Bytel 


ByteO 


Bytel 


IS. sue 

or 

lE.DAO 


(type of 
first item 
in queue) 


Number of bytes in 
first item in network 
data queue. 
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Table 2-4 (Cont.): Status Block Contents After GND$ 

If GND$ completes with an error other than lE.DAO (-13): 

Status Word Status Word 1 

ByteO Byte1 ByteO Byte1 

IE.Arx:x: 



1 . If access verification is enabled, the Network Verification Program at the target node 
evaluates access control information in the connect request before passing the request 
to the target task's network data queue. 

2. The verification task was not installed on the target node, it was set to OFF with the 
NCP SET EXECUTOR VERIFICATION command, or the proper access control file was 
not available. 

3. The account is not in the system account file, the password does not match the one in 
the file, or the object is set to inspect. 



Error/Completion Codes: 

IS . sue The macro completed successfully . 

IS.DAO The macro completed successfully, but some returned optional 

data was lost. 

lE.DAO Data overrun. The network data was longer than the mail buffer. 

As much data as will fit into the mail buffer is transferred to it; any 
remaining data is lost. 

IE . IPC LUN not assigned to NS : . 

lE.NDA There is no data in the network data queue to return. 

lE.NNT The issuing task is not a network task; OPN$ did not execute suc- 

cessfully. 

lE.PRI The network is not accessed on the specified LUN. 

lE.SPC Invalid buffer argument; the buffer assigned to receive network 

data (mail) is not word aligned or is outside the user task address 
space. 



DECnet-RSX MACRO-11 Programming Facilities 



2-45 



GND$ 



Connect Block: 

This section includes Table 2-5, which lists the contents of the short connect 
block, and Table 2-6, which lists the contents of the long connect block. It also 
includes Figure 2-3, an example of an incoming connect short block. 

The source descriptor differs according to the source system type. If the source is 
an RSX system 

■ and the connect request does not include proxy information, you receive a 
Format 1 source desriptor containing the ASCII source task name. 

■ and the connect request includes proxy information, you receive a Format 2 
source descriptor containing the proxy information. 

The access control information that GND$ returns differs according to whether 
access verification is set to ON or OFF for the task. 

Table 2-5: Contents of Incoming Short Connect Block 



Length in 
Symbolic Decimal 
Offset Bytes Contents 



N . CTL * 2 . Temporary logical link address (required by the network; 

do not modify) 

N . SEGZ * 2 . NSP segment size (used by NSP to send message data to 

source) 

DESTINATION DESCRIPTOR 

(20. -byte total) 

N.DFM 1 . Destination descriptor format type: 0, 1 

N.DOT 1. Destination object type: 0-255. 

Descriptor Field for Format 
18. Not used 



* These symbolic offsets are guaranteed to be even (word aligned). 
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Table 2-5 (Cont.): Contents of Incoming Short Connect Block 



Symbolic 
Offset 



Length in 

Decimal 

Bytes 



Contents 



N.SND^ 



6. 



N.SFM 1. 
N.SOT 1. 



Descriptor Fields for Format 1 

N . DDEC * 2 . Destination task name length (equal 
to or less than 16. bytes) 



NODE* 



1 6 . Destination task name 



SOURCE DESCRIPTOR 

(2 6. -byte total) 

Source node name (name of node requesting the connec- 
tion; ASCII, with trailing blanks) 

Source descriptor format type (format 0, 1 , or 2) 

Source object type (object type of task or process request- 
ing the connection: 1-255. for format 0, or for format 1) 

Descriptor Field for Format 

18. Not used 

Descriptor Fields for Format 1 

N.SDEC * 2 . Source descriptor length (equal to or 
less than 16. bytes) 

N.SDE* 16. Source descriptor (ASCII) 

Descriptor Fields for Format 2 

N . SGRP * 2 . Binary UlC group identifier 

N.SMEM * 2 . Binary UIC member identifier 

N.SDRC* 



N.SDR* 



2 . Source descriptor length (equal to or 
less than 1 2 . bytes) 

1 2 . Source descriptor 



* These symbolic offsets are guaranteed to be even (word aligned). 



(continued on next page) 
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Table 2-5 (Cont.): Contents of Incoming Short Connect Block 



Symbolic 
Offset 



Length in 

Decimal 

Bytes 



Contents 



ACCESS CONTROL INFORMATION 

(46.-byte total) 

If no verification is performed 

N . CIDC * 2 . User ID length (equal to or less than 
16. bytes) 

N.CID* 16. User ID 

N.CPSC * 2 . Password length (equal to or less than 
8. bytes) 

N.CPS* 8. Password 

N . C ACC * 2 . Account number length (equal to or 
less than 16. bytes) 

N.CAC* 16. Account number 

If verification is per formed 

N.CDEV 2. Defauh device name 

N.CUNI 1 . Default device unit number 

1 . Not used 

N.CUIC 2 . Log-in UIC from account file 

N . CDDS 1 1 . Default directory string (0 if no 
default string) 



29. Not used 



N.CBL = 98. (not including optional data) 

OPTIONAL DATA 

(18. -byte total) 

N.CDAC* 2. 



N.CDA* 



16. 



Length of optional user data (equal to or less than 16. 
bytes; if no optional data) 

Optional user data sent by source task (0 to 16. bytes) 



These symbolic offsets are guaranteed to be even (word aligned). 



2-48 



DECnet-RSX Programmer's Reference Manual 



GND$ 



Table 2-6: Contents of Incoming Long Connect Block 



Symboiic 
Offset 


Lengtli in 

Decimal 

Bytes 


Contents 


M.CTL* 


2. 


Temporary logical link address (required by the network; 
do not modify) 


M.SEGZ* 


2. 


NSP segment size (used by NSP to send message data to 
source) 

DESTINATION DESCRIPTOR 

(20.-byte total) 


M.DFM 


1. 


Destination descriptor format type: 0,1 


M.DOT 


1. 


Destination object type-. 0-255. 
Descriptor Field for Format 
18. Not used 
Descriptor Fields for Format 1 

M . DDEC * 2 . Destination task name length (equal 
to or less than 16. bytes) 

M . DDE * 16. Destination task name 

SOURCE DESCRIPTOR 

(26. -byte total) 


M.SND* 


6. 


Source node name (name of node requesting the connec- 
tion; ASCII, with trailing blanks) 


M.SFM 


1. 


Source descriptor format type (must be either format or 
format 1) 


M.SOT 


1. 


Source object type (object type of task or process request- 
ing the connection: 1-255. for format 0, or for format 1) 

Descriptor Field for Format 

JLO. i^^L UoCVX 

Descriptor Fields for Format 1 

M.SDEC * 2 . Source descriptor length (equal to or 
less than 16. bytes) 

M.SDE* 16. Source descriptor (ASCII) 



* These symbolic offsets are guaranteed to be even (word aligned). 



(continued on next page) 
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Table 2-6 (Cont.): Contents of Incoming Long Connect Block 

Length in 
Symbolic Decimal 
Offset Bytes Contents 

Descriptor Fields for Format 2 

N.SGRP* 2. Binary UIC group 

N . SMEM * 2 . Binary UIC member 

N . SDRC * 2 . Source descriptor length (equal to or 
less than 12. bytes) 

N.SDR* 12. Source descriptor 

ACCESS CONTROL INFORIMATION 

(126. -byte total) 

If no verification is performed 

M . CIDC * 2 . User ID length (equal to or less than 
39. bytes plus 1 byte for an even byte 
count) 

M.CID* 39. User ID 

1. Not used 

M.CPSC * 2 . Password length (equal to or less than 
39. bytes plus 1 byte for an even byte 
count) 

M.CPS* 39. Password 

1 . Not used 

M.CACC * 2 . Account number length (equal to or 
less than 39. bytes plus 1 byte for an 
even byte count) 

M.CAC* 39. Account number 

1 . Not used 
If verification is performed 
M.CDEV 2. Default device name 
M.CUNI 1 . Default device unit number 

1 . Not used 

* These symbolic offsets are guaranteed to be even (word aligned). 
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Table 2-6: (Cont.) Contents of Incoming Long Connect Block 

Length in 
Symbolic Decimal 
Offset Bytes Contents 

M.CUIC 2 . Log-in UIC from account file 

M.CDDS 11. Default directory string (0 if no 
default string) 

109. Not used 

M.CBL = 178. (not including optional data) 

OPTIONAL DATA 

(18. -byte total) 

M.CDAC * 2. Length of optional user data (equal to or less than 16. 

bytes; if no optional data) 

M . CDA * 16. Optional user data sent by source task (0 to 1 6 . bytes) 

* These symbolic offsets are guaranteed to be even (word aligned). 



Figure 2-3 is an example of an incoming connect block. The figure shows the 
connect block that the following macro created in the source task: 

CONB$$ TACOMA , , 1 , <RECVR> , BLOGGS , < ' P , ' A , ' S> 

The connect block contains the following values: 



Field Value 

Destination descriptor format type 1 

Destination object type (named object) 

Destination task name length 5 

Destination task name RECVR 

Source node name TACOMA 

Source descriptor format type 1 

Source object type (named object) 

Source descriptor length 6 
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Field 



Value 



Source descriptor 



SENDR 



User ID length 



6 



User ID 



BLOGGS 



Password length 



3 



Password 



PAS 



The account number length and account number are omitted because RSX nodes 
do not require account numbers. 

Because the call supplied explicit access control information (user ID and pass- 
word), the incoming connect block contains that information. If outgoing proxy 
is enabled on the source node, the source descriptor contains the proxy informa- 
tion and the source descriptor type is format 2. If verification is on at the target 
node, the password is cleared out before the target task receives the connect 
block. All byte counts and values are in decimal notation. 

This figure illustrates a short connect block. A long connect block has the same 
fields, but the access control information fields are longer, and the symbolic off- 
set names are prefixed with M. instead of N. 
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Figure 2-3: Incoming Connect Blocic 
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N.CTL (not used by user) 
2 N.SEGZ 
4 N.DFM 
6 N.DDEC 
10 N.DDE 



30 N.SND 



36 N.SFM 
40 N.SDEC 
42 N.SDE 



62 N.CIDC 
64 N.CID 



104 N.CPSC 
106 N.CPS 



116 N.CACC 
120 N.CAC 
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OPN$ 

(Access the Network) 

2.5.1 1 OPN$ — Access the Network 

Use: 

Issue OPN$ to establish the task as an active network task and create the task's 
network data queue. Issue OPN$ before issuing any other intertask communica- 
tion macro. 

Formats: 

label: OPN[W]$ [lun]\efn],{status\\ast]{,<links{,lrp]{,^i: .\.CQ]>\ 

OPN[W]$E label,[lun],[efn],[status],[ast]l < links[,lrp]im .LCB] > ] 

OPN[W]$S [lun],[efn],[status],[ast]l < /mife5[,/rp][,NT.LCB] > ] 

Arguments: 

label 

specifies the location of the argument block. See the definition in Section 
2.5.1. 

lun 

assigns a logical unit number to the task's network data queue. You can omit 
this argument if you have already assigned the LUN to NS: by defining the 
symbol .MBXLU in the user program or in a GBLDEF option at task build 
time (Section 1.2.1). Use this LUN in any subsequent GND$, SPA$, GLN$, 
REJ$, or CLS$ macro. 

* efn 

specifies an optional event flag number to set when OPN$ completes. 

* status 

specifies completion status information on return from OPN$ . See the defi- 
nition in Section 2.5.1. 
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ast 

is the address of an optional user-written AST routine to execute after OPN$ 
completes. 

links 

specifies the maximum number of simultaneous, active logical links within 
the task. When the number of active links equals the links value (255- maxi- 
mum), the network rejects any incoming connect request. A value of sets 
no limit as long as network resources are available. Zero is also the default. 

To prevent access to your task, specify a links value of 1 and code the rou- 
tine that processes the GND$ macro to reject all incoming connect requests. 
You can still use CON$ to establish outgoing links. 

Irp 

specifies the link recovery period. The link recovery period is the number of 
minutes that elapses from the time of a physical link failure until the network 
aborts the associated logical link. The Irp must be in the range of through 
32767(decimal). 

When specifying an Irp value, remember that unless your task includes 
checkpoint capabilities, it is locked in memory until the link recovery period 
elapses if it has outstanding I/O when the link fails. This can cause serious 
delays for other system users who need to access the occupied area of mem- 
ory. 

Flag: 

NT.LCB 

specifies that the task transmits and receives long connect blocks that sup- 
port 39. -character user IDs, passwords, and accounts. If a connect request 
for your task arrives with a short connect block, network software copies 
the information in each field to the corresponding field in the long format 
before passing it to your task. The NT.LCB value is 1 . 
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Error/Completion Codes: 

IS . sue The macro completed successfully . 

IE .IFC LUN not assigned to NS : . 

lE.PRI The network is being dismounted, or the user task has already 

accessed the network. 

lE.RSU System resources needed for the network data queue are not 

available. 
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REC$ 

(Receive Data over a Logical Link) 

2.5.12 REC$ — Receive Data over a Logical Linic 

Use: 

Issue REC$ from either task to receive message data over an established logical 
link and store it in a specified buffer. 

Formats: 

label: REC[W]$ lun\efn\\status\\asf\,<buf,buflen> 

REC[W]$E label,[lun],[efn],[status],[ast][, < buf,buflen>] 

REC[W]$S lun,[efn],[status],[ast], < buf,buflen > 

Arguments: 

label 

specifies the location of the argument block. See the definition in Section 
2.5.1. 

lun 

specifies the logical link over which to receive data. If you initiated the con- 
nection, enter the LUN you used in the CON$ macro. If you accepted the 
connection, enter the LUN you used in the ACC$ macro. 

* efn 

specifies an optional event flag number to set when REC$ completes. 

* status 

specifies completion status information on return from REC5S. See the defini- 
tion in Section 2.51, but note this exception: 

Word 1: Contains number of bytes received. 
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ast 

is the address of an optional user- written AST routine to execute after REC$ 
completes. 

* buf 

is the address of the buffer to contain the received message data. 
buflen 

is the length of the receive buffer in bytes (8128. maximum). 

Error/Completion Codes: 

IS. sue The macro completed successfully. 

IE. ABO The logical link was disconnected during I/O operations. 

lE.DAO Data overrun. More message data was transmitted than 

requested. As much data as will fit into the receive buffer is trans- 
ferred to it; any remaining data is lost. 

IE. IPC LUN not assigned to NS: . 

lE.NLN No logical link has been established on the specified LUN. 

lE.NNT The issuing task is not a network task; OPN$ did not execute suc- 

cessfully. 

IE. SPC Invalid buffer argument; either the data buffer {buf) is outside the 

user task address space, or the buffer length {buflen) exceeds 
8128. bytes. 
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REJ$ 

(Reject Logical Link Connect Request) 
2.5.13 REJ$ — Reject Logical Link Connect Request 
Use: 

Issue REJ$ from the target task to reject a logical link connect request. When you 
issue REJ$, you can send 1 to 16. bytes of user data to the requesting task (see the 
out,outlen arguments). 

Formats: 

label: REJ[W]$ {lun]\efn]\status]\ast},<mail\mailen%out,outlen\> 

REJ[W]$E label,[lun],[efn],[status],[ast], < mail,[mailen\[,out,outlen] > 

REJ[W]$S [lun],[efn],[status],[ast], < mail,[mailen][,out,outlen] > 

Arguments: 

label 

specifies the location of the argument block. See the definition in Section 
2.5.1. 

lun 

identifies the logical unit number of the network data queue. Use the same 
LUN you assigned in the OPN$ macro. 

* efn 

specifies an optional event flag number to set when REJ$ completes. 

* status 

specifies completion status information on return from REJ$. See the defini- 
tion in Section 2.5.1. 
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ast 



is the address of an optional user- written AST routine to execute after REJ$ 
completes. 



is the address of the connect block sent by the source task and retrieved by 
GND$. Specify the same address for this and the GND$ mail argument. Con- 
nect block information is required to reject the connection. 



is the length of the connect block in decimal bytes. The default value is 98. 
bytes (N.CBL), the short connect block length, not including optional data. 
For a long connect block, specify 178. bytes (M.CBL), the long connect block 
length, not including optional data. 

out,outlen 

define optional user data to send. See the definition in Section 2.5.1. 



mail 



mailen 



Error/Completion Codes: 



IS. sue 



The macro completed successfully. 



IE. ABO 



The task that requested the connection has aborted or requested 
a disconnect before the rejection could complete. 



IE. BAD 



Either the temporary link address in the connect block is not 
valid, or the optional user data buffer exceeds 16. bytes. 



lE.IFC 



LUN not assigned to NS:. 



lE.NNT 



The issuing task is not a network task; OPN$ did not execute suc- 
cessfully. 



lE.PRI 



The network is not accessed on the specified LUN. 



lE.SPC 



Invalid buffer argument; either the connect block {mail) or the 
optional user data buffer {out) is outside the user task address 
space, or the connect block is not word aligned. 
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SND$ 

(Send Data over a Logical Link) 

2.5.14 SND$ — Send Data over a Logical Link 

Use: 

Issue SND$ from either task to send message data over an established logical link. 
This macro completes when the other task has actually received the data. 

Formats: 

label: SND[W]$ lun,{efn\,{status\\asf\,<buf,huflen> 

SND[W]$E label,[lun],[efn],[status],[ast][, < buf,buflen > ] 

SND[W]$S lun,[efn],[status],[ast], < buf,buflen > 

Arguments: 

label 

specifies the location of the argument block. See the definition in Section 
2.5.1. 

lun 

identifies the logical link over which to send the data. If you initiated the 
connection, enter the LUN you used in the CON$ macro. If you accepted the 
connection, enter the LUN you used in the ACC$ macro. 

* efn 

specifies an optional event flag number to set when SND$ completes. 

* status 

specifies completion status information on return from SND$. See the defini- 
tion in Section 2.5.1, but note this exception: 

Word 1 : Contains number of bytes sent. 
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ast 

is the address of an optional user-written AST routine to execute after SND$ 
completes. 

buf 

is the address of the buffer containing the data to send. 
buflen 

is the length in bytes (8128. maximum) of the data to send. 

Error/Completion Codes: 

IS. sue The macro completed successfully. 

IE .ABO The logical link was disconnected during I/O operations. 

lE.IFC LUN not assigned to NS:. 

lE.NLN No logical link has been established on the specified LUN. 

lE.NNT The issuing task is not a network task; OPN$ did not execute suc- 

cessfully. 

lE.SPC Invalid buffer argument; either the message data buffer {buf) is 

outside the user task address space, or the buffer length {buflen) 
exceeds 8128. bytes. 
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SPA$ 

(Specify User AST Routine) 

2.5.15 SPA$ — Specify User AST Routine 

Use: 

Issue SPA$ from either task to specify a user-written AST routine. The AST rou- 
tine will execute whenever network data arrives in the network data queue. 

Issuing SPA$ affects only the data items that subsequently arrive in the queue. 
However, SPA$ returns a count of all data items in the queue to word 1 of its 
status block, including those that preceded the macro. 

Formats: 

label: SP A[ W] $ {lun\ , [efn] , [status] , {ast\ , < addr > 

SPA[W]$E label,[lun],[efn],[status],[ast][, < addr> ] 

SP A[ W] $ S [lun\ , [efn] , [status] , [ast] , < addr > 

Arguments: 

label 

specifies the location of the argument block. See the definition in Section 
2.5.1. 

lun 

identifies the logical unit number of the network data queue. Use the same 
LUN you assigned in the OPN$ macro. 

* efn 

specifics an optional event flag number to set when SPAS completes. 

* status 

specifies completion status information on return from SPA$. See the defini- 
tion in Section 2.5.1, but note this exception: 

Word 1 : Contains number of items in network data queue. 
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ast 

is the address of an optional user-written AST routine to execute after SPA$ 
completes (see the SPA$ programming note that follows). 

addr 

is the address of a user-written AST routine. This argument is required for 
executing an AST routine. 

You can change the specified AST routine during task execution by specify- 
ing a different starting address or eliminate it by zeroing the starting address. 
When you change the AST during execution, the AST that executes does not 
push extra information onto the stack, as a normal completion AST does. 
Therefore, you need not remove anything from the stack. 



Error/Completion Codes: 

IS . sue The macro completed successfully . 

IE . IFC LUN not assigned to NS : . 

lE.NNT The issuing task is not a network task; OPN$ did not execute 

successfully. 

lE.PRI The network is not accessed on the specified LUN. 

The following example demonstrates how an application can process all net- 
work data at the AST level by using the SPA$ completion AST to simulate the 
network data AST. 
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MAIN CODE 
OPN$S 

SPA$S ... #CMPAST,<SPAAST> ; Set up SPAAST as the AST entry 

; for network data 



; + 



CMPAST - The entry point for completion of the actual SPA directive 
SPAAST - The entry point for each arrival of network data 
.ENABLE LSB 



CMPAST : 


MOV 


(SP)+,IOSB 


Save the SPA$ I/O status block address 




MOV 


RO,-(SP) 


Save RO 




MOV 


#IOSB,R0 


Get the I/O status address 




CMPB 


#IS.SUC,(RO) 


Was the directive successful? 




BNE 


20$ 


If NE, no - just exit from AST 




MOV 


2(R0),R0 


Else, copy current number of ASTs queued 




BEQ 


20$ 


If EQ, nothing queued, exit from AST 




BR 


10$ 


Else, join common code 


SPAAST: 


MOV 


R0,-(SP) 


Save RO 




MOV 


#1,R0 


Set the network data queue count to one 


10$: 


GNDW$S 


,,,,,#GNDSB 


Get the network data item 




BCS 


20$ 


If OS, directive failed 




CMPB 


#IS.SUC,GNDSB 


Was the directive successful ? 




BNE 


20$ 


If NE, no - exit from AST 








... do some processing ... 




SOB 


RD,10$ 


Continue until 


20$: 


MOV 


(SP),RO 


Restore RO 




ASTX$S 




Exit from AST 



.DSABL LSB 
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XMI$ 

(Send Interrupt Message) 

2.5.16 XMI$ — Send Interrupt Message 

Use: 

Issue XMI$ from either task to send an interrupt message over an established logi- 
cal link. XMI$ places the message on the target task's network data queue. The 
target task must issue GND$ to retrieve the message before you can issue another 
XMI$ on the same logical link. Note that XMI$ may complete before the target 
task issues a GND$ to retrieve the interrupt message. 

Formats: 

label: XMI[W] $ lun , [efn] , [status] , [ast] , < int, intlen > 

XMI[W]$E label,[lun],[efn],[status],[ast][, < intjntlen > ] 

XMI[ W] $ S lun , [efn] , [status] , [ast] , < int, intlen > 

Arguments: 

label 

specifies the location of the argument block. See the definition in Section 
2.5.1. 

lun 

specifies the logical link over which to send the interrupt message. If you ini- 
tiated the connection, enter the LUN you used in the CON$ macro. If you 
accepted the connection, enter the LUN you used in the ACC$ macro. 

* efn 

specifies an optional event flag number to set when XMI$ completes. 

* status 

specifies completion status information on return from XMI$. See the defini- 
tion in Section 2.5.1, but note this exception: 

Word 1 : Contains number of bytes sent in message. 
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ast 

is the address of an optional user-written AST routine to execute after XMI$ 
completes. 

int 

is the address of the buffer that contains the 1- to 16. -byte interrupt message 
to send. 

intlen 

is the length in decimal bytes of the message to send 

Error/Completion Codes: 

IS. sue The interrupt message has been transmitted successfully. This 

code does not ensure that GND$ retrieved the message. 

IE. ABO The logical link was disconnected during I/O operations. 

IE. BAD The interrupt message exceeds 16. bytes. 

lE.IFC LUN not assigned to NS: . 

lE.NLN No logical link has been established on the specified LUN. 

lE.NNT The issuing task is not a network task; OPN$ did not execute suc- 

cessfully. 

lE.SPC Invalid buffer argument; the interrupt message buffer {int) is out- 

side the user task address space. 

IE. WLK An interrupt message was transmitted before a previous interrupt 

message had been received by the target task. 
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2.5.1 7 MACRO-1 1 1ntertask Communication Programming Examples 

The following MACRO-1 1 programs are cooperating programs to run on differ- 
ent nodes in the network. The transmitting program, SEN 10, sends messages to 
the receiving program, RECIO. 

These programming examples are included in your tape or disk kit. 
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2.5.17.1 Transmit Example 

The SEN 10 program transmits an interrupt message and 10 data messages to the 
cooperating REC 10 program. 

.TITLE SENIO 

; Copyright (C) 1983, 1985, 1986, 1987 by 

; Digital Equipment Corporation, Maynard, Mass. 



This software is furnished under a license and may be used and copied 
only in accordance with the terms of such license and with the 
inclusion of the above copyright notice. This software or any other 
copies thereof may not be provided or otherwise made available to any 
other person. No title to and ownership of the software is hereby 
transferred. 

The information in this software is subject to change without notice 
and should not be construed as a commitment by Digital Equipment 
Corporat iOn . 

Digital assumes no responsibility for the use or reliability of its 
software on equipment which is not supplied by Digital. 



This program prompts a user for the text of a message to transmit to 
the remote receiving task RECIO. It sends that message as an interrupt 
message and sends 10 data messages with the format "This is message n" 
to RECIO. 

To assemble, use the following command string: 

MAC SENIO, SEN10/-SP= IN: [ 100 , 10 ]NETLIB/ML , IN: [20 , 200 ] SENIO 
To task build, use the following command string: 

TKB SENIO, SEN10/-SP=SEN10, IN: [ 130 , 10 ]NETLIB/LB 

Note: The IN: device must be the DECnet distribution device 
after the PREGEN (if any) has been performed. 

************************************************************** 



. MCALL OPNW$S , CONW$S , SNDW$S , CONB$ $ , ALUN$C , Q lOWSC 
.MCALL EXIT$S,MRKT$C,WTSE$C,CLEF$C,SETF$C,QIO$C 
.MCALL DSCW$S,XMIW$S,ASTX$S 



Data area 



MESN : 
NUM: 
NN=.-MESN 
PRMPT : 



.ASCII /This is message / 
.ASCII 70/ 



Message to transmit 
Message number 



.ASCII /MSG:/ 
.EVEN 



; Prompt for interrupt message 



lOSTN: 
BUFF: 
lOSTB: 
CNT: 



.BLKW 2 

.BLKB 16 

.BLKW 2 

. WORD 



; Completion status for network 

; Interrupt message buffer 

; Completion status for buffer 

; Number of chars in interrupt message 
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ERRCNT : . WORD 
lOSB: .BLKW 



.EVEN 

CONBL: CONB$$ TACOMA, , 1 , <REC10> 



CODE 



START : 



OKI: 



.EVEN 

CLR 

CLEF$C 



MOVB 

ALUN$C 

ALUN$C 

OPNW$S 

TSTB 

BGT 

JMP 

CONW$S 
TSTB 
BLE 
QIO$C 



ERRCNT 
5 



#60,NUM 

1, NS 

2, NS 

#1,#1,#I0STN 

lOSTN 

OKI 

ERRl 

#2 ,#2 , #IOSTN, ,<#CONBL> 
lOSTN 
ERR2 
10. RPR, 



Error count 
I/O status 



; Connect request block 



Initialize error count to zero 
Clear event flag used to make sure 
Interrupt message accepted prior 
to exit 

Initialize message num to zero 
Assign LUN 1 for network data queue 
Assign LUN 2 for logical link 
Create the network data queue 
Test for errors 



; Create logical link to "RECIO' 
; Test for errors 



5, , , I0STB,TRMAST,<BUFF,16. , ,PRMPT,4> ; Accept 

interrupt message from terminal 
(use AST) [16 char max] 





TST 


$DSW ; 


Test for errors 




BLT 


ERR3 






MOV 


#10.,R0 


Set loop counter to 10 


LOOP: 


SNDW$S 


#2,#2,#IOSTN, ,<#MESN,#NN> ; Send message 




TSTB 


lOSTN 


Test for errors 




BLE 


ERR4 






INCB 


NUM ; 


Update message number 




SOB 


RO , LOOP 


Loop if more to send 




WTSE$C 


5 ; 


Make sure terminal message was 








entered before exiting 




DSCW$S 


#2,#2,#IOSTN 


Disconnect network 




EXIT$S 




Exit 


; Terminal AST 


rout ine 




TRMAST: 


MOV 


(SP)+,IOSB 


Pop stack 




MOV 


IOSTB+2 ,CNT 


Obtain number of characters 




XMIW$S 


#2 ,#3 , #IOSTN, ,<#BUFF,CNT>; Transmit interrupt message 








(Note use of EF 3 instead of 








EF 2 - avoid competition) 




TSTB 


lOSTN 


Test for errors 




BLE 


ERRS 






SETF$C 


5 


Set event flag to indicate that 








interrupt message sent 




ASTX$S 




AST exit 


; Error 


handl in 


g - a sample debugging technique 


ERRS : 


INC 


ERRCNT 


■ Determine 


ERR4 : 


INC 


ERRCNT 


which 


ERR3 : 


INC 


ERRCNT 


; error 


ERR2 : 


INC 


ERRCNT 


; occurred 
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ERRl : INC ERRCNT 

MOV ERRCNT, Rl ; Rl contains the error number 

MOV $DSW,R2 ; R2 contains the Directive Status Word 

MOV I0STN,R3 ; R3 contains the first I/O status word 

MOV IOSTN+2,R4 ; R4 contains the 2nd I/O status word 

lOT ; Abort - dump the registers 



. END START 
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2.5.17.2 Receive Example 



Each time REC 10 receives a message from the cooperating program SEN 10, it dis- 
plays THIS IS MESSAGE n on TI:. This is followed by the actual message, which 
arrives as an interrupt message. 

.TITLE RECIO 



Copyright (C) 1983, 1985, 1986, 1987 by 
Digital Equipment Corporation, Maynard, Mass. 

This software is furnished under a license and may be used and copied 
only in accordance with the terms of such license and with the 
inclusion of the above copyright notice. This software or any other 
copies thereof may not be provided or otherwise made available to any 
other person. No title to and ownership of the software is hereby 
transferred. 

The information in this software is subject to change without notice 
and should not be construed as a commitment by Digital Equipment 
Corporation. 

Digital assumes no responsibility for the use or reliability of its 
software on equipment which is not supplied by Digital. 



This example receives short messages from the sender task "SNDIO," 
prints the messages on TI : , disconnects, and exits gracefully. 

To assemble, use the following command string: 

MAC RECIO, REC10/-SP= IN: [ 130 , 10 ]NETL IB/ML, IN: [200 , 200] RECIO 
To task build, use the following command string: 

TKB RECIO, REC10/-SP=REC10 , IN: [ 130 , 10 ]NETLIB/LB 

Note: The IN: device must be the DECnet distribution device 
after the PREGEN (if any) has been performed. 



.MCALL OPNW$S , SPAW$S , RECW$S , GNDW$S , ACCW$S , CLSW$S , NETDF$ 
.MCALL QIOW$S,ALUN$C,CLEF$C,WTSE$C,SETF$C,ASTX$S,EXIT$S 
NETDF$ 



Data area 



BUFl: .BLKB 
.EVEN 



25. 



Buffer for user messages 



BUF2: .BLKB 

lOST: .BLKW 

lOSTl: .BLKW 

I0ST2: .BLKW 

lOSB: .BLKW 

ERRCNT: .WORD 

CNT: .WORD 

CNTB: .BLKB 

FLAG: .WORD 



N.CBL 



2 
2 
2 
1 


2 




Buffer for network messages 
Completion status for network 
Comp. Stat, for Get Net Data 
Comp. Stat, for Accept Connect 
I/O status 
Error count 

User message char count 
Interrupt message char count 
Disconnect flag 



.EVEN 
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; Code 



START : 


CLR 


ERRCNT 


» 


clef $c 


10 . 




ALUN$C 


1,NS 




ALUN$C 


2,NS 




OPNW$S 


#1 #1 #IOST 




TSTB 


lOST 




BLE 


ERRl 




SPAWSS 






TSTB 


lOST 




BLE 


ERR2 




WTSE$C 


10 . 


LOOP : 


RECW$S 


#2 #2 #IOST 




TSTB 


lOST 




BLE 


ERR3 




MOV 


I0ST+2,CNT 




QIOW$S 


#I0.WLB,#5^# 




TST 


FLAG 




BEQ 


LOOP 




CLSW$S 


#1,#1,#I0ST2 




TSTB 


I0ST2 




BLE 


ERRS 




EXIT$S 






BR 


LOOP 


; Error handling - a sample 


ERRS: 


INC 


ERRCNT 


ERRS: 


INC 


ERRCNT 


ERR4 : 


INC 


ERRCNT 


ERR3 : 


INC 


ERRCNT 


ERR2 : 


INC 


ERRCNT 


ERRl : 


INC 


ERRCNT 




MOV 


ERRCNT , Rl 




MOV 


$DSW,R2 




MOV 


I0ST,R3 




MOV 


IOST+2 ,R4 




lOT 




; AST 


handl ing 


for data in n 



Initialize error count to zero 
Clear event flag used to make 

sure connect has occurred 
Assign LUN 1 for network data queue 
Assign LUN 2 for logical link 
Create the network data queue 
Test for errors 

^ST> ; Specify AST handling 
Test for errors 

Wait to make sure connect occurred 



Test for errors 

Obtain character count 
^T,#40>; Type message on 1 
Has disconnect occurred? 
No, post another receive 
Close network 
Test for errors 

Program exit 



Rl = Error number 

R2 = Directive Status Word 

R3 = I/O status block (1st word) 

R4 = I/O status block (2nd word) 

Abort - dump registers 



CMP AST : 


MOV 


(SP)+, lOSB 
RO,-(SP) 


; Save SPA$ I/O status block addr 




MOV 


; Save RO 




MOV 


IOSB,R0 


; Get I/O status block address 




CMPB 


#IS.SUC, (RO) 


; Successful? 




BEQ 


OKA 






JMP 


OUT 




OKA: 


MOV 
BNE 
JMP 


2(R0) ,R0 

0KB 

OUT 


; Get current network data count 


0KB: 


BR 


GET 




NETAST: 


MOV 


RO ,-(SP) 


; Save RO 




MOV 


#1,R0 


; Set network data count to 1 


GET: 


GNDW$S 


#1,#1,#I0ST1, ,<#BUF2,#N 


CBL> ; Get network data 




BCS 


OUT 


; Carry bit set - error 




CMPB 


#IS.SUC, lOSTl 


; Successful? 




BNE 


OUT 






CMPB 


fNT.CON, IOSTl+1 


; Check if connect request 
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BNE OTHER 

ACCW$S #2,#2,#IOST2, ,<#BUF2> ; Accept connection 

TSTB I0ST2 ; Test for errors 

BLE ERR4 

SETF$C 10. ; Set event flag to indicate 

; connect occurred 

BR NEXT 

CMPB #NT.DSC, IOSTl+1 ; Check if disconnect request 

BNE 0THR2 

MOV #1,FLAG ; Set disconnect flag 

BR NEXT ; Go back to main routine 

CMPB #NT. INT, IOSTl+1 ; Check if interrupt message 

BEQ OKC 

JMP ERR6 ; Not a expected command 

MOVB I0ST1+2,CNTB ; Obtain character count 

QIOW$S #IO.WLB,#5,#3, , , , <#BUF2 , CNTB, #40> ; Type interrupt messag 

; (Note use of EF 3 
; instead of EF 5) 

NOP 

DEC RO ; Check if more data 

BEQ. OUT 

JMP GET 

MOV (SP)+,RO ; Restore RO 

ASTX$S ; AST exit 



.END START 
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FORTRAN, COBOL, and BASiC-PLUS-2 

Programming Facilities 



DECnet-RSX has three types of network subroutines: 

■ Intertask communication calls 

■ Remote file access calls 

■ FORTRAN task control calls 

This chapter lists the calls that perform these subroutines in alphabetical order. 
The description for each call includes its use, formats, argument definitions, and 
error/completion codes. All references to FORTRAN pertain to both FORTRAN 
IV and FORTRAN 77. All references to BASIC pertain to BASlC-PLUS-2. Before 
issuing these calls, read Chapter 1. 

3.1 Building a DECnet-RSX Task 

When a FORTRAN, COBOL, or BASIC task uses any DECnet-RSX facility, that 
task must be linked to the library [1,1] NETFOR.OLB. For example, a COBOL task 
named FILES can be built under RSX-llM with the following task builder com- 
mand string: 

FILES,FILES=FILES,LB: [1,1]NETF0R/LB,LB: [1,1]C0BLIB/LB 
/ 

TASK=FILES 
PAR=GEN 
ACTFIL=2 
// 
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You need not assign logical unit numbers (LUNs) for calls to the network (NS:) at 
task build time or in your program. The OPNNT[W], CONNT[W],and ACCNT[W] 
calls assign the LUNs to the network at run time. Assigning a LUN to the network 
at task build time or in your program will not have an adverse effect on the execu- 
tion of the program. Be sure that the LUNs you specify in these three calls are used 
only for network activity while assigned to NS: . 

3.2 Establishing a Network Task 

The first DECnet call you issue must be an open call. To access the network, issue 
one of the following open calls: 

OPNNT Establishes your task as an active network task and creates a 

network data queue for it. 

OPNNT W Performs the same function as OPNNT, but suspends further 

task execution until the call completes. 

After opening the task to the network, you can establish a logical link by issuing 
calls described in this chapter. 

To terminate network operations for a task, issue one of the following closing 
calls: 

CLSNT Terminates a task's network activity, aborts its established 

logical links, and frees all its network logical unit numbers. 

CLSNTW Performs the same function as CLSNT, but suspends further 

task execution until the call completes. 

3.3 Examining I/O Status Blocks 

All calls in this chapter let you include an argument that specifies the address of a 
status block. This address contains completion status information when the call 
completes. 

The status block address is recommended but optional for intertask communica- 
tion and task control calls. It is required for remote file access calls. 

Status blocks are either 1- or 2 -element integer arrays/strings. The BACC, BACCL, 
BFMTO, and BFMTl calls use one-element arrays/strings. In these arrays/strings, a 
return of -1 indicates that you supplied valid arguments; indicates invalid argu- 
ments. 
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Other calls use 2-element arrays/strings. In these arrays/strings, the first status 
word contains an error /completion code for the call, as follows: 

■ A positive value indicates that the call executed successfully. 

■ A negative value indicates that the call did not execute properly. 

■ A null value (0) indicates the call has not yet completed. 

Examine the value of the returned error/completion code to determine why a call 
failed. Appendix E gives a complete list of error/completion codes for intertask 
calls and task control calls. 

The contents of the second status word differ according to the call you issue. Each 
call therefore defines the contents of the second status word. 



3.4 Using Event Flags 

The network file access routines (NFARs) require the exclusive use of two event 
flags. The default event flags are 17 (.TREE) and 18 (.RCEF). You can choose to 
override these defaults by issuing the following commands in the task builder 
command file: 

GBLDEF=.TREF: fa/we 
GBLDEF=.RCEF:fa/Me 

The value variable is a decimal integer from 1 to 64. (33. through 64. are global 
flags). 

3.5 Specifying Connect Block Options 

As Chapter 1 described, a source task builds a connect block before issuing a con- 
nect request. This outgoing connect block contains information about the con- 
nect request's target node and task. It can also specify explicit access control 
information that gives the source task access to an account on the target node. 
Before network software sends the connect block to the target task, it adds infor- 
mation about the source task or user. If you have an RSX-1 IM-PLUS or Micro/ 
RSX system with outgoing proxy enabled, network software also adds proxy 
information (see Section 3.6). At the target node, the target task retrieves the 
incoming connect block from the network data queue. 

Your task can use either long or short connect blocks. Using long connect blocks 
lets your task support user IDs, passwords, and accounts of 39. characters each. 
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Using short connect blocks lets your task support user IDs of up to 16. characters, 
passwords of up to 8. characters, and accounts of up to 16. characters. 

For greatest flexibility, use long connect blocks when writing a new task. How- 
ever, you can continue to use an existing task that uses short connect blocks with- 
out modifying the task. If you change an existing task to use long connect blocks, 
note the added buffer space requirements. Also note that if the task uses proxy 
access, you need not supply values for the access control information fields. 

The connect block size that you choose affects the following intertask communi- 
cation calls: 

Call Connect Block Option 

OPNNT Include the mbxflg argument to specify a long connect block. 

BACC Call BACC to build a short connect block. 

BACCL Call BACCL to build a long connect block. 

CONNT Specify the size appropriate to your connect block type in the tgtblk 

argument. 

ACCNT Use the mailbuf 2Lt%\xme.nt to reference the appropriately-sized buffer. 

GNDNT 

REJ$ 

The connect block size also affects the following FORTRAN task control calls: 
Call Connect Block Option 

ABONCW Specify the appropriate length for the passivd argument. 

RUNCW 

BACUSR Call BACUSR for a short account and user ID information area. 

BACUSL Call BACUSL for a long account and user ID information area. 

When access verification for your task is on, your node's network software 
verifies access rights and removes the access control information before passing 
an incoming connect block to your task. For information on enabling verification 
for a task, refer to the DECnet-RSX Guide to Network Management Utilities. 
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3.5.1 Receiving Connect Block information 

You specify the task's connect block type by including or omitting the mbxflg 
(mailbox flag) argument to the OPNNT (access the network) call. If you specify 
the mbxflg argument, network software uses long connect blocks when passing 
access control information to your task. 

If the source and target tasks use the same connect block size, incoming connect 
block fields map directly to receiving fields. Communicating tasks need not use 
the same connect block size, however. In the GNDNT call, which retrieves the 
connect block from the network data queue, you specify a buffer to hold the 
retrieved information. The buffer that you allocate may or may not equal the 
incoming connect block, but in writing incoming data to your buffer, network 
software always uses the offsets appropriate to the connect block size that your 
OPNNT call specified. 

You receive all information if the source task sends the same size connect block 
that you receive, or if you receive long connect blocks and the source task sends a 
short connect block. However, if you receive short connect blocks and the source 
task sends a long connect block, you may lose some information. Network soft- 
ware writes the received information into the appropriate field if the information 
fits. Information that does not fit into the receiving field causes a data overrun 
error and is lost. 

You can choose to allocate a receiving buffer that is smaller or larger than the 
expected connect block. For example, you might allocate a smaller buffer to 
exclude all but the initial fields, or allocate a larger buffer to receive optional user 
data. The GNDNT call description describes what happens when the task receives 
access control information that is smaller or larger than expected. 

3.6 Using Access Control Information 

An outgoing connect request sends the target node information in order to gain 
access to the target node. You can specify the access control information and/or 
the network software can supply proxy information. Proxy access is available 
only with RSX-1 IM-PLUS or Micro/RSX. 

When you supply explicit access control information for the connect request, 
you specify a user ID, password, and, optionally, an account number. These iden- 
tify the target account on the remote node. You specify the explicit access control 
information by calling BACC or BACCL. These calls build the connect block's 
access control information area. When the target system receives the connect 
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request, it grants access according to what you specified. For information on 
which access control arguments the target system requires, refer to user docu- 
mentation for that system; DECnet-RSX nodes require the user ID and password. 
For more information on explicit access control information, refer to the 
DECnet-RSX Network Management Concepts and Procedures manual. 

You can supply access control information with intertask communication calls, 
and remote file access calls. 

■ Intertask communication calls. A source task supplies access control 
information in the BACC or BACCL call. 

■ Remote file access calls. A source task supplies access control information 
in the ident argument. 

You can also define an alias node name that includes explicit access control infor- 
mation. An alias node name is a user-assigned logical name for a network node. 
When a source task user defines an alias node name, the task can omit the access 
control information; access control information associated with the alias is used 
automatically. The DECnet-RSX Network Management Concepts and Proce- 
dures manual has more information on creating and using alias node names. 

Proxy access, in contrast, eliminates the need to send passwords across the net- 
work. The network managers on both nodes must set up the environment for 
using proxy. Once your network manager enables outgoing proxy, your node 
automatically sends proxy information with all outgoing connect requests. Proxy 
information is the user ID under which the source task is executing. If incoming 
proxy is enabled on the target node, the system grants access according to the 
proxy information and source node name. For information on how a target sys- 
tem verifies proxy access, refer to the DECnet-RSX Guide to Network Manage- 
ment Utilities. 

If an incoming connect request contains both types of access control information, 
the target system uses the explicit information, and not the proxy information, to 
verify access. 



3-6 



DECnet-RSX Programmer's Reference Manual 



3.7 Conventions Used in This Chapter 



The following notation conventions are used in the call and argument descrip- 
tions and examples for intertask communication, remote file access, and task con- 
trol calls in this chapter: 



asterisk 



UPPERCASE 
lowercase italics 



commas, periods, 
parentheses ( ) 



numbers 



square brackets [ 



flags arguments relating to arrays/character strings that 
you must check for information after the call completes. 
For example, the status argument specifies an array/data 
item that stores completion status information when the 
call completes. 

indicates characters to type exactly as shown. 

indicate variables for which you specify or the system 
supplies the actual values . 

must be typed where shown as part of the call format. 
Even if you omit an argument, include the comma that 
delineates its field unless no other arguments follow. 

FORTRAN Example: 

Basic call format: 

CALL BACC ([status],tgtblk,{usersz,user\, 

\passwdsz,passwd\ [ ,accnosz,accn6\) 

Sample call: 

CALL BACC { ,tgtblk , fpasswdsz fpasswd) 

The example omits arguments for status, usersz, user, 
accnosz, and accno. Commas delineate the fields for the 
first three missing arguments, but are unnecessary for 
the two arguments dropped at the end of the call. 

represent octal numbers in calls and examples unless fol- 
lowed by a decimal point. 

Example: 

A 1- to 7 2. -element character string 

enclose optional data. You must specify any argument 
not enclosed by brackets. Do not type the brackets 
when you code a call. 
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In COBOL and BASIC, you can omit an optional argu- 
ment only if you also omit all trailing arguments. How- 
ever, you can enter for an optional argument that you 
want to omit, but that has trailing arguments you want 
to include. 

COBOL Example: 

Basic call format: 

CALL "CONNT" USING lun,[status],tgtblk, 

[outsize, outmessage] , 
[insize , inmessage] . 

This call includes three categories of optional data: 



■ status 

is optional but cannot be omitted because it is fol- 
lowed by a required argument, tgtblk. You can enter 
for status to prevent the return of status informa- 
tion for the call. 



■ outsize , outmessage 

are paired optional arguments that you can omit 
only if you also omit the trailing arguments, insize 
and inmessage. To omit outsize and outmessage, 
but include the arguments that follow, enter null 
arguments (0) for outsize and outmessage. 



■ insize , inmessage 

are paired optional arguments that you can omit 
without specifying null values since there are no 
trailing arguments. 



Sample call: 

CALL "CONNT" USING lun, status, tgtblk, 0,0, insize, inmessage. 

This call specifies status and insize, inmessage, while 
omitting outsize, outmessage by specifying null values 
for these optional arguments. 
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3.8 Intertask Communication 



This section contains descriptions and usage guidelines for the intertask commu- 
nication calls that Table 3-1 lists alphabetically. 

Read the preceding material in this chapter before using these calls. If you are 
unfamiliar with network intertask communication concepts, also read Chapter 1 
carefully. 



Table 3-1 : Intertask Communication Calls 



Call 


Function 


ABTNT 


Abort a logical link 


ACCNT 


Accept a logical link connect request 


BACC 


Build access control information area (short) 


BACCL 


Build access control information area (long) 


BFMTO 


Build a format destination descriptor 


BFMTl 


Build a format 1 destination descriptor 


CLSNT 


End a task's network operations 


CONNT 


Request a logical link connection 


DSCNT 


Disconnect a logical link 


GLNNT 


Get local node information 


GNDNT 


Get data from network data queue 


OPNNT 


Access the network 


RECNT 


Receive data over a logical link 


REJNT 


Reject logical link connect request 


SNDNT 


Send data over a logical link 


WAITNT 


Suspend the calling task 


XMINT 


Send interrupt message over a logical link 
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Each call description includes the format for each language. The generic formats 
for each language are: 



FORTRAN : CALL xxxxx (arguments) 



COBOL: 



CALL ' 'xxxxx' ' USING arguments. 



BASIC: 



CALL xxxxx BY REF (arguments) 



3.8.1 Common Argument Definitions 

This section defines the common arguments for intertask communication calls. A 
general group defines arguments common to all languages and three individual 
groups define arguments specific to FORTRAN, COBOL, and BASIC-PLUS-2. 

GENERAL 

■ outsize, outmessage 

define optional user data to send with certain calls. These are paired 
optional arguments; use both or omit both. 



EXCEPTION 



You cannot omit outsize, outmessage in the CONNT 
call in COBOL and BASIC unless you also omit the 
insize,inmessage arguments. To include 
insize,inmessage without specifying 

outsize, outmessage, enter a null value (0) for both 
outsize and outmessage. (See the example under the 
discussion of square brackets in Section 3 7.) 



outsize 



specifies the length in bytes/characters of the optional user 
data you can send on some operations. It must be an integer 
variable or constant. 



outmessage 



specifies the array /string containing the user data to send. 
This is a 1- to 16. -element byte array for FORTRAN or a 1- to 
16. -element numeric data item/character string for COBOL 
or BASIC. 
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FORTRAN 



■ References to integers imply single-precision integer values. 

■ status 

specifies an array containing completion status information on return from 
the call. If specified, this 2 -element single-precision integer array contains 
the following values when the call completes: 

status{\) returns an error/completion code. Refer to the descriptions 

of individual calls for a list of the possible codes. 

status{2) returns a directive error code if returns a value of 

-40. Otherwise, status{2) contains 0. 

■ tgtblk 

specifies an array where the BACC or BACCL call builds the explicit access 
control information area and the BFMTO or BFMT 1 call builds the destina- 
tion descriptor. A short connect block requires 72. bytes; a long connect 
block requires 152. bytes. The array must start on an even byte (word) 
boundary. A CONNT call passes this array to the target task. 

COBOL 

■ For a COBOL task using the DECnet interface, logical unit number 1 is a 
reserved number and should never be assigned for a lun. 

■ status 

specifies an elementary numeric data item containing completion status 
information on return from the call. If specified, this elementary numeric 
data item contains the following values when the call completes: 

status{\) returns an error /completion code. Refer to the descriptions 

of individual calls for a list of the possible codes. 

status{2) returns a directive error code if status{\)Tctwtns a value of 

-40. Otherwise, status(2) contains 0. 

You cannot omit status if there are trailing arguments, but you can specify 
for status to prevent the return of status information. See the discussion of 
square brackets in Section 3 .7 for more information on omitting optional 
arguments. 
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tgtblk 



specifies a numeric data item that specifies the area where the BACC or 
BACCL call builds the explicit access control information area and the 
BFMTO or BFMTl call builds the destination descriptor. A short connect 
block requires 72. bytes; a long connect block requires 152. bytes. A CONNT 
call passes the explicit access control and destination descriptor information 
to the target task. 



BASIC-PLUS-2 



■ status%{) 

specifies an array containing completion status information on return from 
the call. If specified, this 2 -element integer array contains the following 
values when the call completes: 

status%(0) returns an error/completion code. Refer to the descriptions 
of individual calls for a list of the possible codes. 

status%{\) returns a directive error code if status%{0) returns a value of 
-40. Otherwise, status%{\) contains 0. 

You cannot omit status if there are trailing arguments, but you can specify 
for status to prevent the return of status information. See the discussion of 
square brackets in Section 3 7 for more information on omitting optional 
arguments. 



■ tgtblk$ 

specifies a character string that specifies the area where the BACC or BACCL 
call builds the explicit access control information and the BFMTO or BFMT 1 
call builds the destination descriptor. A CONNT call passes this string to the 
target task. A short connect block requires 72. bytes; a long connect block 
requires 152. bytes. To allocate space for tgtblk$, use the STRING function: 

?g?&/;fe$=STRING$ (152,0) 
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ABTNT 

(Abort Logical Link) 

3.8.2 ABTNT — Abort Logical Link 

Use: 

Call ABTNT from either task to abort a logical link. ABTNT immediately aborts all 
pending transmits and receives, disconnects the link, and frees the LUNassigned 
to the logical link. When you call ABTNT, you can send 1 to 16. bytes/characters 
of user data to the task from which you are disconnecting (see the outsize, 
outmessage arguments). 

Formats: 

FORTRAN: CALL ABTNT[W] (lun,[status][,outsize, outmessage]) 

COBOL: CALL "ABTNT[W]" USING lun,[status][,outsize, outmessage]. 

BASIC: CALL ABTNT[W] BY REF (lun%,[status%( )] 

[,outsize% ,outmessage$]) 

Arguments: 

lun 

identifies the logical link to abort. This value must be an integer variable or 
constant. If you initiated the connection, enter the LUN you used in the 
CONNT call. If you accepted the connection, enter the LUN you used in the 
ACCNT call. 

* status 

specifies completion status information on return from ABTNT. See the defi- 
nition for your language in Section 3 8.1. 

outsize, outmessage 

define optional user data to send. See the definition in Section 3 8.1. 
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ABTNT 

Error/Completion Codes: 

1 The call completed successfully. 

-2 No logical link has been established on the specified LUN. 

-9 The task is not a network task; OPNNT did not execute successfully. 

- 1 3 You are using an invalid buffer; the optional outmessage buffer is out- 
side the user task address space. 

-40 A directive error has occurred. Directive error codes are defined in the 
RSX-1 IM/M-PLUS Executive Reference Manual. 
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ACCNT 



ACCNT 

(Accept Logical Link Connect Request) 

3.8.3 ACCNT — Accept Logical Link Connect Request 

Use: 

Call ACCNT from the target task to establish a logical link with the source task. 
When you call ACCNT, you can send 1 to 16. bytes/characters of user data to the 
source task (see the outsize, outmessage arguments). 

Formats: 

FORTRAN: Ck\A.KCC^i:\Sff]{lun\status\,mailbuf, {outsize, outmessage\) 

COBOL: CALL "ACCNT[W]" USING lun,[status],mailbuf 

[,outsize, outmessage] 

BASIC: CALL ACCNT[W] BY REF (lun% ,[status%()],mailbup 

[,outsize% ,outinessage$]) 

Arguments: 

lun 

assigns the logical link number. This value must be an integer variable or 
constant. Use this LUN when referring to this logical link in any succeeding 
RECNT, SNDNT, XMINT, ABTNT, or DSCNT call. 

* status 

specifies completion status information on return from ACCNT. See the defi- 
nition for your language in Section 3 8.1. 

mailbuf 

specifies a 1- to w-element array /string that contains the connect block. In 
FORTRAN, this array must start on an even byte (word) boundary. For more 
information, see Table 3-2 and the description of mailbuf under GNDNT 
(Section 3.8. 12). 

outsize, outmessage 

define optional user data to send. See the definition in Section 3 8.1. 
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Error/Completion Codes: 

1 The call completed successfully. 

- 1 System resources needed for the logical link are unavailable. 

-3 The task that requested the connection has aborted or requested a dis- 
connect before the connection could complete. 

-5 The temporary link address in the mail buffer is not valid. 

-8 A logical link has already been established on the specified LUN. 

-9 The task is not a network task; OPNNT did not execute successfully. 

- 1 3 You are using an invalid buffer; the mailbufov outmessage buffer is out- 
side the user task address space, or (for FORTRAN) mailbuf is not word 
aligned. 

-40 A directive error has occurred. Directive error codes are defined in the 
RSX-1 IM/M-PL US Executive Reference Manual. 
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BACC 

(Build Access Control Information Area (Short)) 



3.8.4 BACC — Build Access Control Information Area (Short) 



Use: 



Call BACC from the source task to build an area for explicit access control infor- 
mation for the outgoing connect block. BACC supports 16. -character user IDs, 
8. -character passwords, and 16. -character accounts. 

Explicit access control information arguments define your access rights at the 
remote node or process. The target system verifies access control information 
according to its system conventions. If the target node is equipped to verify the 
information, it does so before passing the CONNT call to the target task. For more 
information on access control verification, refer to the DECnet-RSX Network 
Management Concepts and Procedures manual. 

If you have defined an alias node that includes the explicit access control informa- 
tion, or if you use proxy access, you need not call BACC. 



Formats: 



FORTRAN: 



CALL BACC ({status\,tgtblk\usersz,user\, 

\passwdsz,passwd][,accnosz,accno]) 



COBOL: 



CALL "BACC" USING [status],tgtblk,[usersz,user], 

\passwdsz,passwd\[,accnosz,accno]. 



BASIC: 



CALL BACC BY REF ([status%],tgtblk$ ,[usersz% ,user$], 

\passwdsz% ,passwd$][,accnosz% ,accno$]) 
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Arguments: 

* status 

specifies an integer variable containing completion status information on 
return from BACC. On return, the variable is set to -1 if the BACC call com- 
pleted successfully or to if there was an invalid BACC argument. 

In COBOL and BASIC, you cannot omit status, but you can specify for 
status to prevent the return of status information. See the discussion of 
square brackets in Section 3 7 for more information on omitting optional 
arguments. 

* tgtblk 

specifies an array /string in which to build the explicit access control infor- 
mation area. See the definition for your language in Section 3.8.1. 

usersz,user 

specify the user ID. These are paired optional arguments; use both or omit 
both (FORTRAN) or enter for both (COBOL and BASIC). For information 
on omitting arguments in COBOL and BASIC, refer to the discussion of 
optional arguments (square brackets) in Section 3 7. 

usersz specifies the user ID length in bytes/characters. This field is an 

integer variable or constant. 

user specifies the 1- to 16. -element array /string containing the user 

ID. 

passwdsz,passwd 

specify the password that determines your access at the remote node. These 
are paired optional arguments; use both or omit both (FORTRAN) or enter 
for both (COBOL and BASIC). For information on omitting arguments in 
COBOL and BASIC, refer to the discussion of optional arguments (square 
brackets) in Section 3.7. 

passwdsz specifies the password length in bytes/characters. This field is 
an integer variable or constant. 

passwd specifies a 1 - to 8. -element array /string containing the pass- 
word. 
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accnosz,accno 

specify the account number. These are paired optional arguments; use both 
or omit both. 

accnosz specifies the account number length in bytes/characters. Do 
not use this argument for RSX target systems. This field is an 
integer variable or constant. 

accno specifies a 1- to 16. -element array /string containing the 

account number. 

Connect Block Offsets: 



Length 

in Decimal 

Bytes/Characters 


Destination Descriptor 


26. 


Built by BFMTO or BFMTl call 




Access Control 


2. 


User ID length 




(16. bytes/characters or less) 


16. 


User ID 


2. 


Password length 




(8. bytes/characters or less) 


8. 


Password 


2. 


Account number length 




(16. bytes/characters or less) 


16. 


Account number 
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BACCL 

(Build Access Control Information Area (Long)) 
3.8.5 BACCL — Build Access Control Information Area (Long) 
Use: 

Call BACCL from the source task to build an area for explicit access control infor- 
mation for the outgoing connect block. BACCL supports 39. -character user IDs, 
passwords, and accounts. 

The explicit access control information arguments define an account at the 
remote node. The target system verifies access control information according to 
its system conventions. If the target node is equipped to verify the information, it 
does so before passing the CONNT call to the target task. 

If you have defined an alias node name that includes the access control informa- 
tion, or if you use proxy access, you need not call BACCL. For more information 
on access control verification, refer to the DECnet-RSX Network Management 
Concepts and Procedures manual. For more information on using aliases, refer to 
the DECnet-RSX Guide to User Utilities or the DECnet-RSX Network Manage- 
ment Concepts and Procedures manual. For more information on proxy access, 
refer to the DECnet-RSX Guide to Network Management Utilities. 

Formats: 

FORTRAN: CALL BACCL {{status\,tgtblk ,{usersz ,user\, 

\passwdsz ,passwd\ [ , accnosz, accno]) 

COBOL: CALL "BACCL" USING [status],tgtblk,[usersz,user], 

Ipasswdszpasswd] [ , accnosz, accno] . 

BASIC: CALL BACCL BY REF {[status%],tgtblk$ ,[usersz% ,user$], 

\passwdsz% ,passwd$][,accnosz% ,accno$]) 
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Arguments: 

* status 

specifies an integer variable containing completion status information on 
return from BACCL. On return, the variable is set to -1 if the BACCL call 
completed successfully or to if there was an invalid BACCL argument. 

In COBOL and BASIC, you cannot omit status, but you can specify for 
status to prevent the return of status information. See the discussion of 
square brackets in Section 3 7 for more information on omitting optional 
arguments. 

* tgtblk 

specifies an array /string in which to build the explicit access control infor- 
mation area. See the definition for your language in Section 3 8.1. 

usersz,user 

specify the user ID. These are paired optional arguments; use both or omit 
both (FORTRAN) or enter for both (COBOL and BASIC). For information 
on omitting arguments in COBOL and BASIC, refer to the discussion of 
optional arguments (square brackets) in Section 3 7. 

usersz specifies the user ID length in bytes/characters. This field is an 

integer variable or constant. 

user specifies the 1- to 39. -element array /string containing the user 

ID. 

passwdsz,passwd 

specify the password that determines your access at the remote node. These 
are paired optional arguments; use both or omit both (FORTRAN) or enter 
for both (COBOL and BASIC). For information on omitting arguments in 
COBOL and BASIC, refer to the discussion of optional arguments (square 
brackets) in Section 3 7. 

passwdsz specifies the password length in bytes/characters. This field is 
an integer variable or constant. 

passwd specifies a 1- to 39. -element array /string containing the pass- 
word. 
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accnosz,accno 

specify the account number. These are paired optional arguments; use both 
or omit both. 

accnosz specifies the account number length in bytes/characters. Do 
not use this argument for RSX target systems. This field is an 
integer variable or constant. 

accno specifies a 1- to 3 9. -element array /string containing the 

account number. 

Connect Block Offsets: 



Length 

in Decimal 

Bytes/Cliaracters 


Destination Descriptor 


26. 


Built by BFMTO or BFMTl call 




Access Control 


2. 


User ID length 




(39. bytes /characters or less) 


39. 


User ID 


2. 


Password length 




(39. bytes/characters or less) 


39. 


Password 


2. 


Account number length 




(39. bytes/characters or less) 


39. 


Account number 
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BFMTO 

(Build a Format Destination Descriptor) 

3.8.6 BFMTO — Build a Format Destination Descriptor 

Use: 

Call BFMTO from the source task to build a format destination descriptor for the 
connect block. Use a format descriptor to connect only to a target task that re- 
quires specification of an object type. 

Object types group DECnet programs according to function and are identified 
throughout the network by object type codes (see Appendix B). For example, the 
TLK server task, LSN, has an object type code 0X6 (decimal). Any other program 
that provides the same function on another DECnet system also has object type 
code 0X6 (decimal), regardless of its name. 

Formats: 

FORTRAN: CALL BFMTO {[status\,tgtblk,ndsz,ndname,obJtype) 

COBOL: CALL ' BFMTO" USING [status],tgtblk,ndsz,ndname,objtype. 

BASIC: CALL BFMTO BY REF ([status%],tgtblk$ ,ndsz% ,ndname$, 

objtype%) 

Arguments: 

* status 

specifies an integer variable containing completion status information on 
return from BFMTO. On return, the variable is set to .TRUE, (for FORTRAN) 
or to -1 (for COBOL and BASIC) if the BFMTO call completed successfully. It 
is set to .FALSE, (for FORTRAN) or to (for COBOL and BASIC) if there was 
an invalid BFMTO argument. 

In COBOL and BASIC, you cannot omit status, but you can specify for 
status to prevent the return of status information. See the discussion of 
square brackets in Section 3 7 for more information on omitting optional 
arguments. 
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* tgthlk 

specifies an array /string in which to build the destination descriptor. See the 
definition for your language in Section 3.8.1. 

ndsz 

specifies the node name length in bytes/characters. This field must be an 
integer variable or constant. 

ndname 

specifies a 1- to 6-element array /string containing the name of the target 
node. 

objtype 

is the target task's object type. The objtyp argument is an integer variable or 
constant. The object type for a named object is 0. The object type for a num- 
bered object is in the range 1 to 127. for a DECnet task or 128. to 255 . for a 
user task. Refer to Appendix B for a list of object type codes. 

Privileged users can define their own object types. For more information, 
refer to the DECnet-RSX Network Management Concepts and Procedures 
manual. 

Connect Block Offsets: 



Length 

in Decimal 

Bytes/Characters 


Destination Descriptor 


6. 


Destination node name with trailing blanks 


1. 


Descriptor format type (0 for BFMTO) 


1. 


Destination object type (1 to 255 ) 




Descriptor Field for Format 


18. 


Not used 




Access Control 


46. 


Built by BACC or BACCL call 
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BFMT1 

(Build a Format 1 Destination Descriptor) 

3.8.7 BFMT1 — Build a Format 1 Destination Descriptor 

Use: 

Call BFMT 1 from the source task to build a format 1 destination descriptor for the 
outgoing connect block. Use a format 1 descriptor to connect only to a target task 
that requires specification of a task name. 

Formats: 

FORTRAN: CALL BFMT 1 ([status],tgtblk,ndsz,ndname, 

objtype,namesz, name) 

COBOL: CALL "BFMTl " USING {status\,tgtblk,ndsz,ndname, 

obj type, namesz, name. 

BASIC: CALL BFMTl BY REF ([status%],tgtblk$,ndsz% ,ndname$, 

objtypeX ,namesz% ,name$) 

Arguments: 

* status 

specifies an integer variable containing completion status information on 
return from BFMTl. On return, the variable is set to .TRUE, (for FORTRAN) 
or to -1 (for COBOL and BASIC) if the BFMTl call completed successfully. It 
is set to .FALSE, (for FORTRAN) or to (for COBOL and BASIC) if there was 
an invalid BFMTl argument. 

In COBOL and BASIC, you cannot omit status, but you can specify for 
status to prevent the return of status information. See the discussion of 
square brackets in Section 3 7 for more information on omitting optional 
arguments. 

* tgtblk 

specifies an array /string in which to build the destination descriptor. See the 
definition for your language in Section 3 8.1. 
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ndsz 

specifies the node name length in bytes/characters. This field must be an 
integer variable or constant. 

ndname 

specifies the 1- to 6-element array /string that contains the name of the target 
node. 

objtype 

specifies the object type of the target task. For BFMTl, objtype must be 0. 
namesz 

specifies the length of the program name in bytes/characters. This field must 
be an integer variable or constant. 

name 

specifies a 1- to 6-element array /string containing the name of the target pro- 
gram. 

Connect Block Offsets: 



Length 

in Decimal 

Bytes/Characters 


Destination Descriptor 


6. 


Destination node name with trailing blanks 


1. 


Descriptor format type (1 for BFMTl) 


1. 


Descriptor object type (0 for BFMTl) 




Descriptor Fields for Format 1 


2. 


Destination program name length 




(16. bytes/characters or less) 


16. 


Destination program name 




Access Control 


46. 


Built by BACC or BACCL call 
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Examples: 

The following language-specific examples show the code for a BFMTl call, 
including the declaration statements. 

FORTRAN Example: 

INTEGER*2 I0ST(2) ,NDSIZ,OBJTY,PRSIZ 
BYTE NDNAM ( 6 ) , PRGNAM ( 5 ) 
BYTE C0NBLK(120) 

DATA NDNAM/'T', 'A', 'C','0', 'M', 'A'/ 
DATA PRGNAM/'R', 'E', 'C, 'V, 'R'/ 

OBJTY=0 
NDSIZ=6 
PRSIZ=5 



CALL BFMTl (I0ST,C0NBLK,NDSIZ, NDNAM, OBJTY,PRSIZ, PRGNAM) 
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COBOL Example: 

WORKING-STORAGE SECTION. 
01 STORE-STUFF. 



03 


NODNAM 


PIC 


X(6) VALUE "TACOMA" 


03 


TSKNAM 


PIC 


X(6) VALUE "RECVR". 


03 


STAT 


PIC 


X999 USAGE COMP. 


03 


CONBLK 


PIC 


X(120) . 


03 


NLENG 


PIC 


9 USAGE COMP. 


03 


TLENG 


PIC 


9 USAGE COMP. 


03 


DUMMY 


PIC 


X (2). 



PROCEDURE DIVISION 



* BUILD A FORMAT 1 CONNECT BLOCK. * 

MOVE 6 TO NLENG. 
MOVE 5 TO TLENG. 
CALL BFMTl USING 

STAT 

CONBLK 

NLENG 

NODNAM 

DUMMY 

TLENG 

TSKNAM. 



BASIC-PLUS-2 Example: 

-40 CONBLK$=STRING( 120^,0^) 

\ NDNAM.LEN^=65? 
\ TSKNAM. LEN^= 5^ 
\ NDNAM$=" TACOMA" 
\ TSKNAM$="RECVR" 

\ CALL BFMTl BY REF (STAT^, CONBLK$,NDNAM. LEN^, 
NDNAM$ , DUMMY^ , TSKNAM . LEN$? , 
TSKNAM$) 



3-28 



DECnet-RSX Programmer's Reference Manual 



CLSNT 

CLSNT 

(End Task Network Operations) 

3.8.8 CLSNT — End Task Network Operations 

Use: 

Call CLSNT from either task to end that task's network activity, abort all of its log- 
ical links, and free all its network LUNs. If the CLSNT call occurs when data 
remains in the task's network data queue, network software-. 

■ Reschedules the task if pending connect requests arrived while the task was 
active. The task receives these connect requests when it restarts. There is a 
limit of one retry. 

■ Rejects connect requests that arrived while the task was inactive. 

■ Discards interrupt, user disconnect, user abort, or network abort messages. 

Formats: 

FORTRAN: CALL CLSNT[W] [(status)] 

COBOL: CALL "CLSNT[W]" USING [status]. 

BASIC: CALL CLSNT[W] BY REF [(status%( ))] 

Arguments: 

* status 

specifies completion status information on return from CLSNT. See the defi- 
nition for your language in Section 3.8.1. 
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Error/Completion Codes: 

1 The call completed successfully. 

-9 The task is not a network task; OPNNT did not execute success- 

fully. 

- 10 The network is not accessed on this LUN. 

-40 A directive error has occurred. Directive error codes are defined in 

the RSX-llM/M-PL US Executive Reference Manual. 
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CONNT 

(Request Logical Link Connection) 

3.8.9 CONNT — Request Logical Link Connection 

Use: 

Call CONNT from the source task to request a logical link with the target task. 
Before calling CONNT, you must build a connect block. To build the connect 
block's access control area, you call BACC or BACCL; to build its destination de- 
scriptor, you call BFMTO or BFMTl . 

When a remote system receives a connect request, it checks the remote task. If the 
task is currently installed and inactive, the system automatically loads and acti- 
vates it before passing the connect block to the task. After retrieving the connect 
request with a GNDNT call, the task either accepts (ACCNT) or rejects (REJNT) 
the request. You can send 1 to 16. bytes/characters of user data to and/or receive 
1 to 16. bytes/characters of user data from the remote task when it accepts/rejects 
your connect request 

Formats: 

FORTRAN: CALL CONNr[W](lun,[status],tgtblk, [outsize, outmessage] , 

[insizejnmessage]) 

COBOL: CALL "CONNT[W]" USING lun, [status], tgtblk, 

[outsize, outmessage] , 
[insize, inmessage] . 

BASIC: CALL CONNT[W] BY REF (lun%,[status%0],tgtblk$, 

[outsize% ,outmessage$], 
[insize % , inmessage $ ]) 

Arguments: 

lun 

assigns the logical link number. This value must be an integer variable or 
constant. Use this LUN when referring to this logical link in any subsequent 
RECNT, SNDNT, XMINT, ABTNT, or DSCNT call. 
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status 

specifies an array /data item containing completion status information on 
return from CONNT. In COBOL and BASIC, you cannot omit status, but you 
can specify for status to prevent the return of status information. See the 
discussion of square brackets in Section 3 7 for more information on omit- 
ting optional arguments. If specified, this 2 -element integer array /data item 
contains the following values when the call completes: 

■ The first status word — status%{0) (BASIC) or status{\) (FORTRAN, 
COBOL) — contains an error/completion code, as shown in the list that 
follows. 

■ The contents of the second status word — status%(l) (BASIC) or 
status{2) (FORTRAN, COBOL) — depend on the error/completion code 
in the first status word, as shown in the list that follows. 



These are the error/completion codes you can receive in the first status word 
and the corresponding contents of byte in the second status word. Byte 1 of 
the second status word is always 0. 



Error/Completion Code 
First Status Word 


Contents of Byte 
Second Status Word 


Connection accepted 


Received byte count 


Connection accepted with data 


Received byte count 


overrun 




Connection rejected by user with 


Received byte count 


data overrun 




Connection rejected by DECnet 


Reason for rejection (see Appendix A) 


Connection rejected by user 


Received byte count 


Directive error 


Directive error code 


All other cases 






tgtblk 

specifies an array /string containing the explicit access control information 
area and destination descriptor. See the definition for your language in Sec- 
tion 3.8.1. 
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outsize ,outmessage 

define optional user data to send. See the definition in Section 3 8.1 but note 
the exception. 

insize, inmessage 

define user data you can receive from the target task. These are paired 
optional arguments; use both or omit both. 

insize specifies the length in bytes/characters of the user data to 

receive. It must be an integer variable or constant. 

* inmessage specifies the array /string that stores the user data sent by 
the target task. This is a 1- to 16. -element byte array for 
FORTRAN or a 1- to 16. -element character string for 
COBOL or BASIC. 

Error/Completion Codes: 



1 The call completed successfully. 

2 The call completed successfully; the connection was accepted, but 
some returned optional data sent to the target task when you 
called CONNT was lost. 

- 1 System resources needed for the logical link are unavailable . 

-4 The connection was rejected and some optional data was lost (the 

data sent to the target task when you called CONNT). 

-5 Either an optional user data buffer exceeds 16. bytes/characters, or 

the field length count in the connect block is too large. 

-7 The connection was rejected by the network (see the reject reason 

codes in Appendix A). 

-8 A logical link has already been established on the specified LUN. 

-9 The task is not a network task; OPNNT did not execute success- 

fully. 

-12 The connection was rejected by the remote user task. 
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-13 You are using an invalid buffer; the tgtblk, inmessage, or 

outmessage buffer is outside the user task address space or (for 
FORTRAN) tgtblk is not word aligned. 

-40 A directive error has occurred. Directive error codes are defined in 

the RSX-1 IM/M-PLUS Executive Reference Manual. 
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DSCNT 

(Disconnect a Logical Link) 

3.8.1 DSCNT — Disconnect a Logical Linic 

Use: 

Call DSCNT from either task to disconnect the logical link and free the logical unit 
number. This call lets all pending transmits complete. While they are completing, 
the task continues to receive messages. When the last transmit has completed, the 
task aborts all pending receives and disconnects the link. The I/O status block 
gives an abort status for each aborted receive. 

When you call DSCNT, you can send 1 to 16. bytes/characters of user data to the 
target task (see the outsize, outmessage arguments). 

Formats: 

FORTRAN: CALL DSCNT[W] (lun,[status][,outsize,outmessage]) 

COBOL: CALL "DSCNT[W]" USING lun,{status\[,outsize,outmessage\. 

BASIC: CALL DSCNT[W] BY REF (lun%,[status%{)], 

[outsize% ,outmessage$]) 

Arguments: 

lun 

specifies the logical link to disconnect. It must be an integer variable or con- 
stant. If you initiated the connection, enter the LUN you used in the CONNT 
call. If you accepted the connection, enter the LUN you used in the ACCNT 
call. 

* status 

specifies completion status information on return from DSCNT. See the defi- 
nition for your language in Section 3 8.1. 

outsize, outmessage 

define optional user data to send. See the definition in Section 3-8.1. 
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Error/Completion Codes: 

1 The call completed successfully. 
-2 No logical link has been established on the specified LUN. 

-5 The optional user data exceeds 16. bytes/characters. 

-9 The task is not a network task; OPNNT did not execute successfully. 

- 10 The network is not accessed on this LUN. 

-13 You are using an invalid buffer; the outmessage buffer is outside the 
user task address space. 

-40 A directive error has occurred. Directive error codes are defined in the 
RSX-1 IM/M-PLUS Executive Reference Manual. 
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GLNNT 

(Get Local Node Information) 

3.8. 11 GLNNT — Get Local Node Information 
Use: 

Issue GLN$ from either task to place the name and default NSP segment size of the 
local node in a specified buffer. 

Getting the local node name can be helpful if two tasks on the same node use the 
network interface to communicate. Each task can issue GLN$ and use the 
returned local node name as the destination in a connect request. You can also use 
GLN$ in a task that displays the local node name. 

The default NSP segment size tells you how NSP segments data transmitted on a 
logical link. By knowing the default NSP segment size, you can adjust the length 
of message blocks to transmit for most efficient use of transmit buffers (large data 
buffers). 

Formats: 

FORTRAN: CALL GLNNT[W] ([status], buf[en,buf) 

COBOL: CALL "GLNNT[W]" USING [status],buflen,buf- 

BASIC: CALL GLNNT[W] BY REF ([status%( )],buften% ,buj%) 

Arguments: 

* status 

specifies completion status information on return from GLNNT. See the defi- 
nition for your language in Section 3.8. 1 . 

bu/len 

specifies an array /string containing the received data length. If you specify 6 
bytes/characters, only the local node name is returned. If you specify 8. 
bytes/characters, both the node name and the default NSP segment size are 
returned. This value must be an integer variable or constant. 
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buf 

specifies the array /string containing the received data. In FORTRAN, the 
buffer must start on an even byte (word) boundary. On return from the call, 
the data is stored as follows: 



Length 




in Bytes/ 




Characters 


Contents/Meaning 


6 


Local node name in ASCII (left justified and filled with 




spaces if the name is less than 6 bytes/characters) 


2 


Default NSP segment size 



Error/Completion Codes: 

1 The call completed successfully. 

-4 Data overrun. The network data was longer than the specified buffer. As 
much data as fits into the buffer is transferred to it; any remaining data is 
lost. 

-9 The task is not a network task; OPNNT did not execute successfully. 

-10 The network is not accessed on this LUN. 

-13 You are using an invalid buffer; the buffer specified to receive network 
data is outside the user task address space, or (for FORTRAN) it is not 
word aligned. 

-40 A directive error has occurred. Directive error codes are defined in the 
RSX-1 IM/M-PL US Executive Reference Manual. 
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GNDNT 

(Get Network Data) 

3.8.12 GNDNT — Get Network Data 
Use: 

Call GNDNT from either task to get data from that task's network data queue and 
store it in the specified mail buffer (see mailhuf). On completion, the variable 
specified by the type argument contains a code that indicates what type of mes- 
sage GNDNT retrieved. The code indicates one of the following unsolicited mes- 
sage types: 

Connect request type code 1 

Interrupt message type code 2 

User disconnect notice type code 3 

User abort notice type code 4 

Network abort notice type code 5 

Only one GNDNT request can be outstanding. If you issue a GNDNT while 
another GNDNT is outstanding, your request completes with error code -14. 

If GNDNT retrieves a connect request, it writes the accompanying connect block 
information to the mail buffer. You can use a long or short connect block depend- 
ing on the length of the user IDs, passwords, and accounts you expect to receive. 
For information about the incoming connect block, see the "Connect Block" sec- 
tion of this call description. 

Formats: 

FORTRAN: CALL GNDNT[W] (\status\type \mailsz\\mailbuS\, 

[Itonly] , [immeci][,typmsk]) 

COBOL: CALL "GNDNT[W]" USING [status],type,mailsz,mailbuf, 

[Itonly] , [immed] [ , typmsk] . 

BASIC: CALL GNDNT[W] BY REF ([status%( )],type%,mailsz%, 

mailbuf$ , {ltonly% ] ,[immed% ] 
[,typmsk%]) 
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Arguments: 

* status 

specifies a 2-element integer array /data item that contains completion status 
information on return from GNDNT. In COBOL and BASIC, you cannot omit 
status, but you can set its value to to prevent the return of status informa- 
tion. See the discussion of square brackets in Section 3 7 for more informa- 
tion on omitting optional arguments. If specified, this 2-element integer 
array/data item contains the following values when the call completes: 

■ The first status word — status%{0) (BASIC) or status(l) (FORTRAN, 
COBOL) — contains an error/completion code, as shown in Status 
Table A. 

■ The contents of the second status word — status%{l) (BASIC) or 
status{2) (FORTRAN, COBOL) — depend on the error/completion code 
in the first status word, as shown in Status Table A. 

Status Table A shows the error/completion codes you can receive in the first 
status word and the corresponding contents of byte in the second status 
word. Byte 1 of the second status word is always 0. 

Status Table A 



First Status Word 



Second Status Word 



GNDNT completes 
with an error 

GNDNT completes 
successfully and 
the Itonly flag is 
-1 (.TRUE.): 

GNDNT completes 
successfully and 
the Itonly flag is 
(.FALSE.): 



-40 

-n (other than -40) 



+ n 



+ n 



Directive error code 


The low-order byte contains 
the number of bytes/charac- 
ters in the first network data 
item in the queue. 

Depends on the data message 
type. For each message type, 
Status Table B lists the con- 
tents of the second status 
word. 
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Status Table B shows the contents of the second status word for each type of 
message successfully retrieved by GNDNT. 



Status Table B 



Type 
Code 


Message 
Type 


Low-Order Byte 


High-Order Byte 


1 


Connect 
request 


Number of 
bytes/characters in 
the connect block. 


Access verification* and 
privilege code: 

1 = Nonprivileged requesting 
user. 

2 = Privileged requesting user. 
= No verification done.* 

-1 = Verification failed. ** * 


Z 


Interrupt 
message 


Number of 
bytes/characters in 
the message. Zero 
indicates that no 
message was 
received. 


LUN on which the notice was 
received. 


3 


User 

disconnect 






4 


User 

disconnect 






5 


Network 
abort 


Reason for network 
abort. Refer to 
Appendix A for 
information on the 
codes. 


LUN on which the notice was 
received. 



* If access verification is enabled, the Network Verification Program evaluates 
the access control information in the connect request before passing the incoming 
request to the task's network data queue. 

* * The verification task was not installed on the target node, or it was set to OFF 
with the NCP SET EXECUTOR VERIFICATION command, or the proper access con- 
trol file was not available. 

* * * Either the account is not in the system account file or the password does not 
match the one in the file. 



FORTRAN, COBOL, and BASIC-PLUS-2 Programming Facilities 



3-41 



GNDNT 

* type 

specifies an integer variable indicating a data message type code on return 
from GNDNT. The code indicates the type of data message GNDNT placed 
in the mail buffer. Status Table B lists the codes and tells what message types 
they represent. 

mailsz 

specifies the size of the task's mail buffer in bytes/characters. In FORTRAN, 
you can omit this integer variable or constant if you specify Itonly as .TRUE. 
In COBOL and BASIC, you can set it to if you specify Itonly as -1 . Other- 
wise, mailsz must be a value greater than 0. 

The incoming data is written to the buffer according to the offsets appropri- 
ate to the connect block type that you specified in the OPNNT call. 

You can allocate a mail buffer that is equal to, smaller than, or larger than the 
expected connect block and optional data. To receive an entire connect 
block, allocate space according to the N.CBL or M.CBL length: 

Short connect block 98 . bytes (N . CBL) 

Long connect block 178. bytes (M . CBL) 

You can add space for optional data: 

Optional data Up to 16. bytes 

Optional data leangth field 2. bytes 

Network software writes the retrieved information to the buffer field by 
field, according to the offsets of the specified connect block type. If the mail 
buffer and the incoming connect block are different sizes, the following 
results occur. 

Mail Buffer Size Result 

You allocate a buffer that is No error occurs, 

large than the incoming 
connect block. 

You allocate a buffer that is Connect block data is written field by field 

smaller than a full connect block into the buffer until no more fits. A data 

(IS.DAO) completion status results. 
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Mail Buffer Size 



Result 



You allocate a buffer for re- 
ceiving a short connect block 
and instead receive a long 
connect block. 



If the incoming data fits according to the 
short connect block offsets, you get all the 
data, but a data overrun (IS.DAO) comple- 
tion status results. 



If the data in any incoming field exceeds 
the size of the analogous receiving field, 
the data in that field is lost. The length 
value for the field becomes 0, and a data 
overrun (IS.DAO) completion status 



results. 



* 



mailhuf 



specifies a 1- to w-element array /string containing the network data on return 
from GNDNT (see Table 3-2). In FORTRAN, this array must start on an even 
byte (word) boundary; you can omit it if you specify Itonly as .TRUE. In 
COBOL and BASIC, you can set it to if you specify Itonly as -1 . 



specifies dynamic assignment of mail buffer space. When you specify Itonly 
as .TRUE. (FORTRAN) or -1 (COBOL and BASIC), the type variable returns 
the type code of the first message in the network data queue, and the low- 
order byte of the second status word returns its length. The message is not 
removed from the queue or placed in the mail buffer. 

If you specify the typmsk argument, you must specify Itonly as in COBOL 
and BASIC; in FORTRAN, you must omit Itonly or specify it as .FALSE. In 
COBOL and BASIC, you can omit Itonly only if you omit all trailing argu- 
ments. For information on omitting arguments in COBOL and BASIC, refer 
to the discussion of square brackets in Section 3 7. 



Itonly 



immed 



specifies GNDNT action based on data in the network data queue. 
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Data in 
Network 

Value of immed Queue? GNDNT Action 



.TRUE. (FORTRAN) Yes 

or-1 (COBOL and 

BASIC) 

No 

.FALSE. (FORTRAN) Yes 
or (COBOL and 
BASIC) or omitted 

No 



Completes normally 

Completes with error code -6 
(no data in queue) 

Completes normally 

Does not complete until there is data 
in the queue 



You cannot omit immed in COBOL or BASIC unless you also omit all trailing 
arguments. For information on omitting arguments in COBOL and BASIC, 
refer to the discussion of square brackets in Section 3 -7. 

typmsk 

specifies the data type to select from the network data queue. Normally, 
GNDNT returns items from the network data queue on a first-in, first-out 
basis. However, typmsk lets you select the first item on the queue that 
matches a specific message type and/or LUN. You specify an integer variable 
or constant, as follows: 



l\/lessage Type 
(Byte 0) 



Logical Unit Number 
(Byte1) 



1 Connect request 

2 Interrupt message 

3 User disconnect 

4 User abort 

5 Network abort 

Selects any message type 
on the specified LUN 



(Selects the first LUN to request a 

connection.) 
or LUN 
or LUN 
or LUN 
or LUN 
LUN 



For example, to select the first interrupt message (type 2) on LUN 3 from the 
network data queue, you use a variable for the typmsk argument, declare it 
as an integer, and assign it a value. You code the argument as(3*256.) + 2. 
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Specifying in byte 1 returns the first message of the type specified in byte 
0, regardless of the LUN. 

With typmsk, you must also include mailsz and mailbuf. In COBOL and 
BASIC, you must also specify Itonly as 0. In FORTRAN, you can omit Itonly 
or specify it as .FALSE. 

Connect Block: 

Table 3-2 lists the contents of an incoming connect block. The access control 
fields differ according to the connect block size that you specified in the OPNNT 
call. 

The source descriptor differs according to the source system type. If the source is 
an RSX system 

■ and the source node did not send proxy information, you receive a Format 1 
source descriptor containing the ASCII source task name. 

■ and the source node sent proxy information, you receive a Format 2 source 
descriptor containing the proxy information. 



Table 3-2: Incoming Connect Block 



Length In 




Decimal Bytes/ 




Characters 


Contents 


2. 


Temporary logical link address 




(required by the network; do not modify) 


2. 


NSP segment size 




(used by NSP to send message data to source) 




DESTINATION DESCRIPTOR 




(20.-byte/character total) 


1. 


Destination descriptor format type 




for BFMTO, or 1 for BFMTl) 




Descriptor Field for Format 


18. 


Not used 



(continued on next page) 
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Table 3-2 (Cont.): Incoming Connect Block 



Length in 
Decimal Bytes/ 
Characters 


Contents 




Dcscviptof Fields foT PoTtncit 1 


2. 


Destination program name length 




(equal to or less than 16. bytes/characters) 


16. 


Destination program name 




SOURCE DESCRIPTOR 




(26.-byte/character total) 


6. 


Source node name 




(name of node requesting the connection; ASCII, 




with trailing blanks 


1. 


Source descriptor format type 




(lormat U, l , or z) 


1 

1 . 


Source object type 




(object type of program requesting connection: 




1-255 for format 0, or for format 1 or 2) 




Descriptor Field for Format 


18. 


Not used 




Descriptor Fields for Format 1 


2. 


Source descriptor length 




(equal to or less than 16. bytes/characters) 


16. 


Source descriptor 




Descriptor Fields for Format 2 


2. 


Binary UIC group identifier 


2. 


Binary UIC member identifier 


2. 


Source descriptor length 




(12. bytes or less) 


12. 


Source descriptor 
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Table 3-2 (Cont.): Incoming Connect Block 



Length in 
Decimal Bytes/ 

Characters Contents 







ACCESS CONTROL 
(46.-byte/character total) 






If no verification performed 


2. 




Source program user ID length 

(equal to or less than 16. bytes/characters for a short connect 
block or 40. characters for a long connect block) 


16. or 
39. + 
1. 


Source program user ID, short connect block 
Source program user ID, long connect block 
Not used 


2. 




Source program password length 

(16. bytes/characters or less for a short connect block or 40. char- 
acters or less for a long connect block) 


8. or 
39. + 
1. 


Source program password, short connect block 
Source program password, long connect block 
Not used 


2. 




Account number length 

(16. bytes/characters or less for a short connect block or 40. char- 
acters or less for a long connect block) 


16. 
39. 
1. 


or 

+ 


Account number, short connect block 
Account number, long connect block 
Not used 

If verification performed 


2. 




uciciUiL ucvicc ii<tiiic lur ciCdiiii<tLiuii piugiiim 


1. 




Default device unit number 


1. 




Not used 


2. 




Log-in UlC from account file 
used for destination program 


11. 




Default directory string 
(0 if no default string) 


29. 




Not used 



(continued on next page) 
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Table 3-2 (Cont.): Incoming Connect Block 



Lennth in 




Decimal Bytes/ 




Characters 


Contents 




OPTIONAL DATA 




(1 8. -byte/character total) 


2. 


Length of optional user data 




(16. bytes/characters or less; if no optional data) 


16. 


Optional user data sent by source program 




(0 to 16. bytes/characters) 



Error/Completion Codes: 

1 The call completed successfully. 

2 The call completed successfully, but some returned optional data was 
lost. 

-4 Data overrun. The network data was longer than the mail buffer. As 

much data as fits into the mail buffer is transferred to it; any remaining 
data is lost. 

-6 There is no data in the network data queue to return. 

-9 The task is not a network task; either OPNNT did not execute success- 

fully, or CLSNT was issued with this GNDNT pending. 

- 1 The network is not accessed on this LUN . 

-13 You are using an invalid buffer; the mail buffer is outside the user task 
address space, or (for FORTRAN) it is not word aligned. 

- 1 4 A GNDNT is already pending . 

-40 A directive error has occurred. Directive error codes are defined in the 
RSX-1 IM/M-PL US Executive Reference Manual. 
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OPNNT 

(Access the Network) 

3.8.13 OPNNT — Access the Network 

Use: 

Call OPNNT to establish the task as an active network task and create the task's 
network data queue. Call OPNNT before any other network subroutine. 

Formats: 

FORTRAN: CALL OPNNT[W] ([lun],[status],[mstat],[count],[lrp][,mhxf[g]) 

COBOL: CALL "OPNNT[W] " USING [lun],[status],[mstat], 

[count],[lrp][,mhxf[g]. 

BASIC: CALL OPNNT[W] BY REF {[lun%],[status%( )],[mstat%( )], 

[count] , [Irp % ][ ,mbxflg]) 

Arguments: 

lun 

specifies a logical unit number for the task's network data queue. This value 
must be an integer variable or constant. You can omit this argument if you 
have already assigned the LUN to NS: by using the GBLDEF option of 
.MBXLU at task build time (Section 1.2.1). When you omit lun in COBOL or 
BASIC, you must also omit all trailing arguments. For information on omit- 
ting arguments in COBOL and BASIC, refer to the discussion of square 
brackets in Section 3.7. 

* status 

specifies completion status information on return from OPNNT. See the def- 
inition for your language in Section 3 8.1. 
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* 



mstat 



specifies a 3 -element integer array (or elementary numeric data item for 
COBOL) to contain current status information for the task's network data 
queue. When specified ( + ), the mstat array /data item is updated whenever 
data arrives or is retrieved by GNDNT. Do not use this array /data item for 
other purposes while the task is active on the network. 

Values returned in this array /data item are: 

mstat{\) Number of items in the network data queue 

mstat(2) Data type of the first data item: 



1 - Connect request 

2 - Interrupt message 

3 - User disconnect 

4 - User abort 

5 - Network abort 



specifies the maximum number of simultaneously active connections the 
task accepts. When the number of active logical links equals the comw? value, 
the network rejects any incoming connect request. This integer variable or 
constant must not exceed 255 (decimal). A value of (which is also the 
default) sets no limit as long as network resources are available. 

To prevent access to your task, specify a count value of 1 so that GNDNT 
rejects all incoming connect requests. You can still establish outgoing links 
by using CONNT. 



specifies the link recovery period. The link recovery period is the number of 
minutes that elapses from the time of a physical link failure until the associ- 
ated logical link is irrecoverable. This integer variable or constant must be in 
the range of through 32767 (decimal). 

When specifying an Irp value, remember that your task is locked in memory 
until the link recovery period has elapsed if the task has outstanding I/O 
when the link fails. This can cause serious delays for other system users who 
need to access the occupied area of memory. 



mstat(^) 



Length of first data item 



count 



Irp 
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mbxflg 

specifies that the task has a mail buffer that supports sending and receiving 
long connect blocks. For a task that uses long connect blocks, set the mbxflg 
value to an integer variable or constant with the value 1 . For a task that uses 
short connect blocks, omit the argument. 

Error/Completion Codes: 

1 The call completed successfully. 

- 1 System resources needed for the network data queue are not available. 

-10 The network is being dismounted, or the user task has already accessed 
the network. 

-40 A directive error has occurred. Directive error codes are defined in the 
RSX-1 IM/M-PL US Executive Reference Manual. 
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RECNT 

(Receive Data over a Logical Link) 

3.8.14 RECNT — Receive Data over a Logical Link 
Use: 

Call RECNT from either task to receive data over an established logical link and 
store it in a specified buffer. 

Formats: 

FORTRAN: CALL RECNT[W] {lun,[status],msize,indata) 

COBOL: CALL "RECNT[W]" USING lun, [status], insizejndata. 

BASIC : CALL RECNT[W] BY REF (lun % , [statusX ( )] , insizeX , indata$) 

Arguments: 

lun 

specifies the logical unit number for the logical link over which to receive 
data. It must be an integer variable or constant. If you initiated the connec- 
tion, enter the LUN you used in the CONNT call. If you accepted the connec- 
tion, enter the LUN you used in the ACCNT call. 

* status 

specifies completion status information on return from RECNT. See the defi- 
nition for your language in Section 3 8.1 but note this addition: If a positive 
value or -4 (data overrun) is returned in the first status word, the second 
status word contains the number of bytes/characters of data received. 

insize 

specifies the receive data buffer length in bytes/characters. This integer vari- 
able or constant can be a maximum of 8128 (decimal). 

* indata 

specifies the array /string containing the received message data. 
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Error/Completion Codes: 

1 The call completed successfully. 

-2 No logical link has been established on the specified LUN. 

-3 The logical link was disconnected during I/O operations. 

-4 Data overrun. More message data was transmitted than requested. As 
much data as fits into the receive buffer is transferred to it; any remain- 
ing data is lost. 

-9 The task is not a network task; OPNNT did not execute successfully. 

- 1 3 You are using an invalid buffer; either the indata array /string is outside 
the user task address space, or the buffer size (insize) exceeds 8128. 
bytes/characters. 

-40 A directive error has occurred. Directive error codes are defined in the 
RSX-1 IM/M-PL US Executive Reference Manual. 
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REJNT 

(Reject Logical Link Connect Request) 

3.8.15 REJNT — Reject Logical Link Connect Request 
Use: 

Call REJNT from the target task to reject a logical link connect request. With 
REJNT, you can send 1 to 16. bytes/characters of user data to the requesting task 
(see the outsize, outmessage arguments). 

Formats: 

FORTRAN: CALL REJNT[W] {[status\,mailbuJ\,outsize,outmessage]) 

COBOL: CALL "REJNT[W]" USING {status\,mailbuf, [outsize, outmessage]. 

BASIC : CALL REJNT[W] BY REE {{status%{ )] ,mailbuf$ , 

[outsize% ,outmessage$]) 

Arguments: 

* status 

specifies completion status information on return from REJNT. See the defi- 
nition for your language in Section 3.8.1. 

mailbuf 

specifies the 1- to ^-element array /string containing information necessary 
to reject the connect request. In FORTRAN, this array must start on an even 
byte (word) boundary. GNDNT refers to this same array /string. 

outsize, outmessage 

define optional user data to send. See the definition in Section 3 8.1. 
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Error/Completion Codes: 

1 The call completed successfully. 

-3 The task that requested the connection has aborted or has requested a 
disconnect before the connection could complete. 

-5 Either the temporary link address in the mail buffer is not valid, or the 

optional user data buffer exceeds 16. bytes/characters. 

-9 The task is not a network task; OPNNT did not execute successfully. 

- 1 The network is not accessed on this LUN. 

- 1 3 You are using an invalid buffer; the mailbufot outmessage array/string 
is outside the user task address space, or (for FORTRAN) the mailbuf 
array is not word aligned. 

-40 A directive error has occurred. Directive error codes are defined in the 
RSX-llM/M-PL US Executive Reference Manual. 
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(Send Data over a Logical Link) 



3.8.1 6 SNDNT — Send Data over a Logical Link 



Use: 

Call SNDNT from either task to send message data over the logical link. 



Formats: 

FORTRAN: CALL SNDNT[W] (lun,[status],outsize,outdata) 

COBOL: CALL "SNDNT[W]" USING lun,[status],outsize,outdata. 

BASIC: CALL SNDNT[W] BY REF (lun%,[status%( )],outsize% ,outdata$) 



Arguments: 

lun 

specifies the logical unit number for the logical link over which to send data. 
This value must be an integer variable or constant. If you initiated the con- 
nection, enter the LUN you used in the CONNT call. If you accepted the con- 
nection, enter the LUN you used in the ACNNT call. 

* status 

specifies completion status information on return from SNDNT. See the defi- 
nition for your language in Section 3 8. 1 but note this addition: If 1 is 
returned in the first status word, the second status word contains the num- 
ber of bytes/characters of transmitted data. 

outsize 

specifies the length in bytes/characters of the data to send. This integer vari- 
able or constant can be a maximum of 8128 (decimal). 

outdata 

specifies a 1- to w-element array /string containing the message data to send. 
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Error/Completion Codes: 

1 The call completed successfully. 

-2 No logical link has been established on the specified LUN. 

-3 The logical link was disconnected during I/O operations. 

-9 The task is not a network task; OPNNT did not execute successfully. 

-13 You are using an invalid buffer; either the outdata array /string is out- 
side the user task address space, or the buffer size {outsize) exceeds 
8128. bytes/characters . 

-40 A directive error has occurred. Directive error codes are defined in the 
RSX- 1 IM/M-PL US Executive Reference Manual. 
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WAITNT 

(Suspend the Calling Task) 

3.8.1 7 WAITNT — Suspend the Calling Task 

Use: 

Call WAITNT from any task to suspend that task's operation until completion of a 
call specified by one of the associated status blocks. 

Formats: 

FORTRAN 
COBOL: 
BASIC: 

Arguments: 

* index 

specifies an integer variable containing the positional number of the status 
block associated with the call that has completed. 

In COBOL and BASIC, you cannot omit index, but you can specify for 
index to prevent the return of index information. See the discussion of 
square brackets in Section 3 7 for more information on omitting optional 
arguments. 

status 1 ,statusn 

specify one or more status blocks. WAITNT completes when any one of the 
calls associated with a status block in this list completes. 



CALL WAITNT ([index] ,statusl ,statusn) 

CALL "WAITNT" USING [index],statusl ,...,statusn. 

CALL WAITNT BY REF {[index%],statusl%( ), . ..,statusn%( )) 
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XMINT 

(Send Interrupt Message) 

3.8.18 XMINT — Send Interrupt Message 
Use: 

Call XMINT from either task to send an interrupt message over an established logi- 
cal link. This call places the message you send on the target task's network data 
queue. The target task must issue a GNDNT call to retrieve the message before 
you can issue another XMINT. 

Formats: 

FORTRAN: CALL XMINT[W] (lun,[status],intsize,mtmsg) 

COBOL: CALL "XMINT[W]" USING lun\status\,intsize,intmsg. 

BASIC: CALL XMINT[W] BY REF (lun% ,[status%0],intsize% ,intmsg$) 

Arguments: 

lun 

specifies the logical unit number for the logical link over which to send the 
interrupt message. This value must be an integer variable or constant. If you 
initiated the connection, enter the LUN you used in the CONNT call. If you 
accepted the connection, enter the LUN you used in the ACCNT call. 

* status 

specifies completion status information on return from XMINT. See the defi- 
nition for your language in Section 3 8.1. 

intsize 

specifies the length in bytes/characters of the interrupt message to send. It 
must be an integer variable or constant. 

intmsg 

specifies a 1- to 16. -element array /string containing the interrupt message to 
send. 
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Error/Completion Codes: 

1 The call completed successfully. 

-2 No logical link has been established on the specified LUN. 

-3 The logical link was disconnected during I/O operations. 

-5 The interrupt message exceeds 16. bytes/characters. 

-9 The task is not a network task; OPNNT did not execute successfully. 

- 1 1 An interrupt message was transmitted before a previous interrupt mes- 
sage had been received by the remote task. 

-13 You are using an invalid array /string; the intmsg array /string is outside 
the user task address space. 

-40 A directive error has occurred. Directive error codes are defined in the 
RSX-1 IM/M-PL US Executive Reference Manual. 
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3.8.19 FORTRAN Intertask Communication Programming Examples 

The following two programs are examples of FORTRAN intertask communica- 
tion. They are cooperating tasks. FTNTRN is a transmit task; FTNREC is a receiver 
task. 

These programming examples are included in your tape or disk kit. 
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3.8.19.1 Transmit Example 



The FTNTRN program accesses the network, connects to FTNREC, transmits 
inquiries to FTNREC, and processes responses. When FTNTRN completes send- 
ing inquiries, it disconnects the link, stops accessing the network, and exits. 

c 
c 

C Copyright (C) 1983, 1985, 1986, 1987 by 

C Digital Equipment Corporation, Maynard, Mass. 

C 

C 

C This software is furnished under a license and may be used and copied 
C only in accordance with the terms of such license and .with the 
C inclusion of the above copyright notice. This software or any other 
C copies thereof may not be provided or otherwise made available to any 
C other person. No title to and ownership of the software is hereby 
C transferred. 
C 

C The information in this software is subject to change without notice 
' C and should not be construed as a commitment by Digital Equipment 
C Corporation. 
C 

C Digital assumes no responsibility for the use or reliability of its 

C software on equipment which is not supplied by Digital. 

C 

C 

c 
c 

C FTNTRN - Transmit inquiries to FTNREC and process responses 
C 

C To task build, use the following command string: 
C 

C FTNTRN, FTNTRN = FTNTRN 

C LB: [1,1]NETF0R/LB 

C LB: [1,1]F4P0TS/LB 

C LB: [1,1]RMSLIB/LB (if RMS is included) 

C / 

C UNITS=10 

C ACTFIL=4 

C EXTTSK=1000 (if RMS is included) 

C // 

C 

C Note: This task uses a long connect block. 



C 



INTEGER 
INTEGER 
BYTE 
BYTE 

L0GICAL*1 



MLTYP , RECS I Z , SNDS I Z , MESNUM , XM I TS , NDLEN , TSKLEN 
MBXFLG,NETLUN,LNKLUN, I0ST(2) ,MSTAT(3) 
ERRMES(2) ,TSKNAM(6) ,NDNAM(6) ,DEFN0D(6) ,DEFTSK(6) 
CONBLK(152) ,SNDBUF(50) ,RECBUF(10) 
STAT, IMMED 



C 
C 

c 



Specify the default node and task names 



DATA 
DATA 



DEFNOD /'R' , 'E' , 'M' , 'N' , '0' , "DV 
DEFTSK /'R','E','C','V','E','R'/ 



C 
C 
C 



Specify flags for long connect block and immediate mode 



DATA 



MBXFLG, IMMED /I,. TRUE./ 



C 
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C LUNs for the network mailbox and the logical link 
C 

DATA NETLUN,LNKLUN /I, 2/ 

C 

C Specify transmit count, send buffer size, and receive buffer size 
C 

DATA XMITS,SNDSIZ,RECSIZ 720,50,10/ 

C 

C Get the node and task names 
C 

10 TYPE 250 I* Ask for node-name 

READ(5,260) (NDNAM(NDLEN) ,NDLEN=1 , 6) !* Get the name 
DO 20 NDLEN=6,1,-1 !* Loop to find length of name 

IF (NDNAM(NDLEN) .NE. ' ') GOTO 40!* If not a space, get task-name 

20 CONTINUE 

DO 30 1=1,6 

30 NDNAM( I )=DEFNOD( I ) !* Default node name 'MASTER' 

NDLEN=6 !* Length of default name 

40 TYPE 270 !* Ask for the task-name 

READ(5,260) (TSKNAM(TSKLEN) ,TSKLEN=1 , 6 ) !* Get it 
DO 50 TSKLEN=6,1,-1 !* TSKLEN is length of task-name 

IF ( TSKNAM( TSKLEN ) .NE. ' ') GOTO 70 !* If not space, access network 

50 CONTINUE 

DO 60 1=1,6 

60 TSKNAM{ I )=DEFTSK( I ) !* Default task name 'RECVER' 

TSKLEN=6 !* Length of default name 

C 

C Access network - MBXFLG indicates that we will use a long connect block* 
C 

7 CALL OPNNTW ( NETLUN , I OST , MST AT , , , MBXFLG ) 

IF (lOST(l) .NE.DGOTO 140 !* If failure, just exit 

C 

C Build a Format 1 connect block 
C 

CALL BFMT1(STAT,C0NBLK,NDLEN,NDNAM, , TSKLEN, TSKNAM) 

IF (STAT)GOTO 80 !* If success, go on 

TYPE 200 !* Else, type out a failure 

!* notification 
GOTO 130 !* and exit 

C 

C Connect to the task on the remote node 
C 

8 CALL CONNTW ( LNKLUN , I OST , CONBLK ) 

IF (lOST(l) .EQ.DGOTO 90 !* If success, confirm it 

TYPE 240,IOST !* Else print status block 

GOTO 130 !* Deaccess the network 

!* and exit 

90 TYPE 220 !* Print connect confirmation 

!* to network and exit 

C 

C Send and receive messages to and from the remote node 
C 

DO 120 MESNUM=1,XMITS 

(continued on next page) 
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c 

C First get any error messages sent from the other side in interrupt 

C messages 

C 

IF (MSTAT(l) .EQ.0)GOTO 100 !* If MSTAT(1)=0 no messages 

!* are there 

CALL GNDNTW(I0ST,MLTYP,2,ERRMES, ,IMMED,2) !* Get the message 
IF ( lOST(l) .NE.DGOTO 100 !* If we couldn't get the message, 

!* just ignore it 
TYPE 210,ERRMES(1) !* Print out the message 

C 

C Send the inquiry 
C 

100 CALL SNDNTW(LNKLUN, IOST,SNDSIZ,SNDBUF) 

IF (lOST(l) .EQ.DGOTO 110 !* If success, continue 

TYPE 210,MESNUM !* Otherwise, type out an 

!-* error message 
GOTO 120 I* and start a new message 

C 

C Receive the response from the remote node 
C 

110 CALL RECNTW(LNKLUN, IOST,RECSIZ,RECBUF) 

IF (lOST(l) .EQ.DGOTO 120 !* If success, continue 

TYPE 210,MESNUM !* Otherwise, type out an 

!* error message 

120 CONTINUE 
C 

C Disconnect the link 
C 

TYPE 230 !* Print out disconnect message 

CALL DSCNTW(LNKLUN, lOST) 



c 






C Come 
C 


here to 


close the network and exit 


130 


CALL 


CLSNTW 


140 
/— 


STOP 


'End of program execution' 


C FORMAT Statements 


200 


FORMAT 


(' Error building connect block' 


210 


FORMAT 


(' Error on inquiry ',13) 


220 


FORMAT 


( ' Link enabled ' ) 


230 


FORMAT 


( ' Link disabled' ) 


240 


FORMAT 


(' Connect fail: lOST = ',216) 


250 


FORMAT 


('$Node-name <REMNOD>: ') 


260 


FORMAT 


(6A1) 


270 


FORMAT 


{'$Task-name <RECVER>: ') 




END 
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3.8.19.2 Receive Example 

The FTNREC program receives inquiries from FTNTRN. It returns errors to 
FTNTRN as interrupt messages, which FTNTRN then displays on the terminal. 

c 
c 
c 

C Copyright (C) 1983, 1985, 1986, 1987 by 

C Digital Equipment Corporation, Maynard, Mass. 

C 

C 

C This software is furnished under a license and may be used and copied 
C only in accordance with the terms of such license and with the 
C inclusion of the above copyright notice. This software or any other 
C copies thereof may not be provided or otherwise made available to any 
C other person. No title to and ownership of the software is hereby 
C transferred. 
C 

C The information in this software is subject to change without notice 
C and should not be construed as a commitment by Digital Equipment 
C Corporation. 
C 

C Digital assumes no responsibility for the use or reliability of its 

C software on equipment which is not supplied by Digital. 

C 

C 

C FTNREC. FTN - Receive inquiries from FTNTRN and send back responses 
C 

C To task build, use the following command string: 
C 

C FTNREC , FTNREC = FTNREC 
C LB: [1,1]F4P0TS/LB 
C LB: [1,1]NETF0R/LB 

C LB: [1,1]RMSLIB/LB (if RMS is included) 

C / 

C UNITS=10 
C ACTFIL=4 

C EXTTSK=1000 (if RMS is included) 

C TASK=RECVER 
C // 

c 

C Note: This task uses a long connect block. 
C 

INTEGER NETLUN,LNKLUN,MLTyP, INDEX , NUMBER , NUMMES 

INTEGER MBXFLG,RECSIZ,SNDSIZ, INTSIZ 

INTEGER MSTAT( 3 ) , IOST( 2 ) , lOSTl ( 2 ) , I0ST2 ( 2 ) 

BYTE RECBUF(50) ,SNDDAT(10) ,MLBX(178) , INTMES(2) 

C 

C Specify LUNs for the network and the logical link 
C 

DATA NETLUN,LNKLUN /I, 2/ 

C 

C Specify sizes for the receive buffer, send buffer, and interrupt buffer 
C 

DATA RECSIZ,SNDSIZ, INTSIZ /50,10,2/ 

C 

C Initialize some variables 

^ (continued on next page) 
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NUMMES =0 I* Number of messages received 

MBXFLG =1 !* Use long connect block 

C 

C Access the network - use the long connect block 
C 

CALL OPNNTW ( NETLUN , I OST , MSTAT , , , MBXFLG ) 
IF (lOST(l) .EQ. 1) GOTO 8 

TYPE *, 'Cannot access the network, status = ISTAT 
GOTO 100 

8 IF (MSTAT(l) .EQ. 0) GOTO 40 !* If nothing in mailbox, 

!* just close and exit 
10 CALL GNDNT(I0ST1,MLTYP,178,MLBX) !* Issue Get Network Data 
20 CALL WAITNT( INDEX, lOSTl, I0ST2) !* Wait for a completion 

IF (INDEX .EQ. 2) GOTO 50 !* If INDEX=2, a receive 

! * has been completed 

C 

C We've received network data 
C 

IF (lOSTld) .NE. 1) GOTO 40 !* If GNDNT failed, close 

!* network and exit 

IF (MLTYP .GE. 3) GOTO 40 !* If MLTYP>=3 the link has 

I * been broken 

IF (MLTYP .EQ. 2) GOTO 10 !* If MLTYP=2 we've received 

!* an interrupt message 
!* — issue a new GNDNT 

C 

C We've received a connect request - issue an accept 
C 

CALL ACCNTW ( LNKLUN , I OST , MLBX ) 

IF (lOST(l) .NE. 1) GOTO 10 !* If failure, issue 

! * a new GNDNT 

C 

C Issue a receive to pick up data 
C 

30 CALL RECNT ( LNKLUN, I0ST2,RECS I Z,RECBUF) 

GOTO 10 !* Issue a new receive and 

!* wait for a completion 

C 

C Come here upon receiving a disconnect or abort 
C 

40 CALL CLSNTW !* Close the network 

GOTO 100 !* and exit 

C 

C Come here if we receive an inquiry 
C 

50 NUMMES =NUMMES+1 !* Update the message count 

IF (I0ST2(1) .EQ. 1) GOTO 60 !* If I0ST2(1)-1 all's okay 

C 

C If there was an error, return an interrupt message with message number 
C 

INTMES(1)=NUMMES !* Send the message number 

CALL XMINT ( LNKLUN, lOST, INTSIZ, INTMES) !* Issue a new receive 

GOTO 70 ! 

C 
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C Here the user can look at the data received in RECBUF and respond by 

C placing the requested information into SNDDAT 

C 

C Send back the data and issue a new receive 
C 

6 CALL SNDNTW ( LNKLUN , I OST , SNDS I Z , SNDDAT ) 
70 CALL RECNT(LNKLUN, I0ST2,RECSIZ,RECBUF) 

GOTO 20 !* Wait for a completion 

C 

C Exit program 
C 

100 STOP 'End of program execution' !* Halt the program 

END !* and exit 
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3.8.20 COBOL Intertask Communication Programming Examples 

The following two programs are examples of COBOL intertask communication. 
They are cooperating tasks. COBTRN is a transmit task; COBREC is a receiver 
task. 

These programming examples are included in your tape or disk kit. 
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3.8.20.1 Transmit Example 



This program sends inquiries to the cooperating COBREC program on a remote 
node. 

* 

* Copyright (C) 1983, 1985, 1986, 1987 by 

* Digital Equipment Corporation, Maynard, Mass. 
* 

* 

* This software is furnished under a license and may be used and copied 

* only in accordance with the terms of such license and with the 

* inclusion of the above copyright notice. This software or any other 

* copies thereof may not be provided or otherwise made available to any 

* other person. No title to and ownership of the software is hereby 

* transferred. 
* 

* The information in this software is subject to change without notice 

* and should not be construed as a commitment by Digital Equipment 

* Corporation. 
* 

* Digital assumes no responsibility for the use or reliability of its 

* software on equipment which is not supplied by Digital. 
* 

IDENTIFICATION DIVISION. 
PROGRAM- ID. COBTRN. 

************************************************* 
* 

* This is the transmit program of the DECnet intertask 

* communication example programs for COBOL. 
* 

* To task build, use the following command string: 
* 

* COBTRN , C0BTRN=C0BTRN ,[1,1] NETFOR/LB , C8 1 L I B/LB , RMS L IB/LB 

* / 

* UNITS=10 

* ACTFIL=4 

* EXTTSK=1000 (if RMS is included) 

* // 
* 

* This task illustrates the use of a long connect block. 
* 

************************************************************** 

ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER . PDP- 1 1 . 
OBJECT-COMPUTER. PDP-11. 
INPUT-OUTPUT SECTION. 
FILE -CONTROL. 

SELECT DUMMY-FILE ASSIGN TO "COBTRN. DUM" . 

DATA DIVISION. 

FILE SECTION. 

FD DUMMY- FILE 

LABEL RECORD STANDARD. 
01 DUMMY-FILE-REC. 

(continued on next page) 
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02 FILLER PIC X(132) . 

WORKING -STORAGE SECTION. 
01 MSGS. 

03 MSGl. 

05 FILLER 

05 MSGl-STATl 
05 FILLER 
05 MSGl -STAT 2 
03 MSG2. 

05 FILLER 

05 MSG2-STAT1 

05 FILLER 

05 MSG2-STAT2 
03 MSG3. 

05 FILLER 

05 MSG3-ERR1 
03 MSG4. 

05 FILLER 

05 MSG4-NUM1 
03 MSG5. 

05 FILLER 

05 MSG5-NUM1 
1 ARRAYS , 
03 lOST. 

05 lOSTAT OCCURS 2 TIMES PIC S9999 USAGE COMP. 
3 MSTAT . 

05 MSTATS OCCURS 3 TIMES PIC S9999 USAGE COMP. 
01 STORE-STUFF. 



03 


MBXFLG 


PIC 


99 


COMP VALUE 


1. 


03 


TEN 


PIC 


99 


COMP VALUE 


10 


03 


OPNLUN 


PIC 


99 


COMP VALUE 


2. 


03 


RESULT-REC 


PIC 


X(80) . 






03 


IN-FILE 


PIC 


X(6) . 






03 


NODNAM 


PIC 


X(6) . 






03 


TSKNAM 


PIC 


X(9) . 






03 


FILLER 


PIC 


X. 






03 


STAT 


PIC 


S999 


USAGE COMP. 




03 


CONBLK 


PIC 


X(72) . 






03 


NLENG 


PIC 


9 


USAGE COMP, 




03 


TLENG 


PIC 


9 


USAGE COMP, 




03 


CONLUN 


PIC 


99 


COMP VALUE 


3. 


03 


XMITS 


PIC 


99 


COMP VALUE 


20 


03 


MESNUM 


PIC 


99. 






03 


MLTYP 


PIC 


9. 






03 


FILLER 


PIC 


9. 






03 


MLBXSZ 


PIC 


99 


COMP VALUE 


2. 


03 


ERRMES 


PIC 


X(2) . 






03 


DUMMY 


PIC 


X(2) . 






03 


IMMED 


PIC 


S 


COMP VALUE • 


-1. 


03 


TYPMSK 


PIC 


S99999, 







PIC 


X(32) 






PIC 


X(ll) 






PIC 


X( 25 ) 


PIC 


-qqqqq 

Z3 ^ ZJ Z> 


PIC 


X(ll) 


PIC 


-99999 


PIC 


X(20) 


PIC 


X(2) . 


PIC 


X(31) 


PIC 


99. 


PIC 


X(34) 


PIC 


99. 



VALUE " NETWORK OPEN FAILED, 
"lOST(l) = ". 

VALUE " I0ST(2) = ". 



VALUE " CONNECT FAIL, lOST(l) 

It _ n 



VALUE " I0ST(2) = ". 
VALUE " ERROR ON INQUIRY # 



VALUE " ERROR ON INQUIRY DURI 
"NG SEND: ". 



VALUE " ERROR ON INQUIRY DURI 
"NG RECEIVE: ". 
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03 FILLER PIC 9. 

03 SNDSIZ PIC 99 COMP VALUE 50. 

03 SNDBUF PIC X(50) . 

03 RECSIZ PIC 99 COMP VALUE 10. 

03 RECBUF PIC X(10) . 

PROCEDURE DIVISION. 
Al 00 -START. 

*************************************************^ 

* * 

* Input node name and receiver task name from * 

* terminal. * 

* * 
************************************************* 

DISPLAY "ENTER NODE-NAME <MASTER>". 

ACCEPT IN- FILE. 

MOVE IN- FILE TO NODNAM, 

DISPLAY "ENTER TASK-NAME <RECVER>" . 

ACCEPT IN- FILE. 

MOVE IN-FILE TO TSKNAM. 

***************************************************************** 

* * 

* Access the network. If the access is unsuccessful, * 

* print an error message and exit. * 

* * 
***************************************************************** 

CALL "OPNNTW" USING 
OPNLUN 
lOST 
MS TAT 
TEN 


MBXFLG. 
IF lOSTAT (1) = 1 

NEXT SENTENCE 

ELSE 

MOVE lOSTAT (1) TO MSG 1- STAT 1 
MOVE lOSTAT (2) TO MSG1-STAT2 
DISPLAY MSGl 
GO COOO-END. 

***************************************************************** 

* * 

* Build a FORMAT 1 connect block. If the call did * 

* not complete successfully, print an error message * 

* and deaccess the network. * 

* * 
***************************************************************** 

MOVE 6 TO NLENG. 
MOVE 6 TO TLENG. 
CALL "BFMTl" USING 
STAT 



(continued on next page) 
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CONBLK 
NLENG 
NODNAM 
DUMMY 
TLENG 
TSKNAM 
IF STAT NOT = 

NEXT SENTENCE 

ELSE 

DISPLAY "ERROR BUILDING CONNECT BLOCK" 
GO BIOO-CLOSE. 

************************************************ 

* * 

* Connect to the task on the remote node. If the * 

* call completes unsuccessfully, print an error message * 

* and close the network. Otherwise, print "Link * 

* enabled" message. * 

* * 
***************************************************************** 

CALL "CONNTW" USING 

CONLUN 

lOST 

CONBLK. 
IF lOSTAT(l) = 1 

NEXT SENTENCE 

ELSE 

MOVE SPACES TO RESULT-REC 
MOVE lOSTAT(l) TO MSG2-STAT1 
MOVE I0STAT(2) TO MSG2-STAT2 
MOVE MSG2 TO RESULT-REC 
DISPLAY RESULT-REC 
GO BIOO-CLOSE. 
DISPLAY "LINK ENABLED". 

***************************************************************** 

* * 

* Send and receive messages from the remote node. * 

* If there is something on the network data queue * 

* (MSTATS (1) > D), get the message. * 

* * 
***************************************************************** 

PERFORM LOOP VARYING MESNUM FROM 1 BY 1 UNTIL MESNUM = XMITS, 

LOOP. 

IF MSTATS (1) = 

NEXT SENTENCE 

ELSE 

CALL "GNDNTW" USING 
lOST 
MLTYP 
MLBXSZ 
ERRMES 
DUMMY 
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IMMED 
TYPMSK 
IF lOSTAT(l) = 1 

NEXT SENTENCE 

ELSE 

MOVE SPACES TO RESULT-REC 
MOVE ERRMES TO MSG3-ERR1 
MOVE MSG 3 TO RESULT-REC 
DISPLAY RESULT-REC. 

***************************************************** 



* * 

* Send a message to the task on the remote node. If * 

* unsuccessful, print an error message and start the * 

* next transmission. * 

* * 



***************************************************************** 

CALL "SNDNTW" USING 

CONLUN 

lOST 

SNDSIZ 

SNDBUF. 
IF lOSTAT(l) = 1 

NEXT SENTENCE 

ELSE 

MOVE SPACES TO RESULT-REC 
MOVE MESNUM TO MSG4-NUM1 
MOVE MSG4 TO RESULT-REC 
DISPLAY RESULT-REC 
GO LOOP. 

***************************************************************** 



* * 

* Receive a message from the remote node. If * 

* unsuccessful, print an error message and start * 

* the next transmission. If successful, simply * 

* start the next transmission. * 

* * 



***************************************************************** 



CALL "RECNTW" USING 

CONLUN 

lOST 

RECSIZ 

RECBUF. 
IF lOSTAT(l) = 1 

NEXT SENTENCE 

ELSE 

MOVE SPACES TO RESULT-REC 
MOVE MESNUM TO MSG5-NUM1 
MOVE MSGS TO RESULT-REC 
DISPLAY RESULT-REC. 

(continued on next page) 
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**************************************************** 

* * 

* Deaccess the network. * 

* * 
***************************************************************** 



BOOO-ENDLOOP. 

DISPLAY "LINK DISABLED". 
CALL "DSCNTW" USING 

CONLUN 

lOST. 

***************************************************************** 

* * 

* Close the network and exit. * 

* * 
***************************************************************** 



BIOO-CLOSE. 

CALL "CLSNTW". 

DISPLAY "END OF EXECUTION". 
CO 00 -END. 

STOP RUN. 



3-74 



DECnet-RSX Programmer's Reference Manual 



3.8.20.2 Receive Example 



The COBREC program receives inquiries from COBTRN. It returns errors to 
COBTRN as interrupt messages, which COBTRN then displays on the terminal. 

* 

* Copyright (C) 1983, 1985, 1986, 1987 by 

* Digital Equipment Corporation, Maynard, Mass. 

* 

* This software is furnished under a license and may be used and copied 

* only in accordance with the terms of such license and with the 

* inclusion of the above copyright notice. This software or any other 

* copies thereof may not be provided or otherwise made available to any 

* other person. No title to and ownership of the software is hereby 

* transferred. 
* 

* The information in this software is subject to change without notice 

* and should not be construed as a commitment by Digital Equipment 

* Corporation. 
* 

* Digital assumes no responsibility for the use or reliability of its 

* software on equipment which is not supplied by Digital. 
* 

IDENTIFICATION DIVISION. 
PROGRAM-ID. COBREC. 

************************************************* 
* 

* This is the receive program of the DECnet intertask 

* communication example programs for COBOL. 
* 

* To task build, use the following command string: 
* 

* COBREC , COBREC=COBREC ,[1,1] NETFOR/LB , C8 IL I B/LB , RMSL I B/LB 

* / 

* UNITS=10 

* ACTFIL=4 

* EXTTSK=1000 (if RMS is included) 

* // 
* 

* This program illustrates the use of a long connect block. 
* 

************************************************************* 

ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER . PDP- 1 1 . 
OBJECT-COMPUTER . PDP- 1 1 . 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 

SELECT DUMMY-FILE ASSIGN TO "COBREC . DUM" . 

DATA DIVISION. 
FILE SECTION. 
FD DUMMY- FILE 

LABEL RECORD STANDARD. 
01 DUMMY-FILE-REC. 

(continued on next page) 
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02 FILLER PIC X(132) . 



WORKING-STORAGE SECTION. 
01 ARRAYS. 
03 lOST. 

05 lOSTAT OCCURS 2 TIMES PIC S9999 USAGE COMP. 
03 MSTAT. 

05 MSTATS OCCURS 3 TIMES PIC S9999 USAGE COMP. 
03 lOSTl. 

05 lOSTATl OCCURS 2 TIMES PIC S9999 USAGE COMP. 
03 I0ST2. 

05 I0STAT2 OCCURS 2 TIMES PIC S9999 USAGE COMP. 
01 STORE-STUFF. 



03 


OPNLUN 


PIC 


99 


COMP VALUE 


2. 


03 


MBXFLG 


PIC 


99 


COMP VALUE 


1. 


03 


MLTYP 


PIC 


9 


USAGE COMP. 




03 


MLSIZ 


PIC 


99 


COMP VALUE 


98 


03 


MLBOX 


PIC 


X(98) . 






03 


INDX 


PIC 


99 


USAGE COMP. 




03 


ACCLUN 


PIC 


99 


COMP VALUE 


3. 


03 


RECSIZ 


PIC 


99 


COMP VALUE 


50 


03 


RECBUF 


PIC 


X(50) . 






03 


NUMMES 


PIC 


99 


COMP VALUE 


0. 


03 


INTSIZ 


PIC 


9 


COMP VALUE 


6. 


03 


INTMES 


PIC 


X(6) . 






03 


SNDSIZ 


PIC 


99 


COMP VALUE 


10 


03 


SNDDAT 


PIC 


X(10) . 







PROCEDURE DIVISION. 



***************************************************** 

* * 

* Access the network. If the call completes * 

* unsuccessfully, exit. * 

* * 
***************************************************************** 



AlOO-START. 

CALL "OPNNTW" USING 
OPNLUN 
lOST 
MSTAT 



MBXFLG. 
IF lOSTAT (1) = 1 

NEXT SENTENCE 

ELSE 

GO GIOO-END. 
IF MSTATS (1) = GO ClOO-CLOSNET . 

***************************************************************** 

* * 

* Check to see if there is anything on the task's * 

* data queue. * 

* * 

***************************************************************** 
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BIOO-NETDAT. 

CALL "GNDNT" USING 
lOSTl 
MLTYP 
MLSIZ 
MLBOX. 



********************************************** 

* * 

* Wait for completion of a GNDNT or RECNT call. If a * 

* RECNT call completes (INDEX = 2), process a receive. * 

* If a GNDNT call completes unsuccessfully, close the * 

* network and exit. If the type of data message in * 

* the mailbox is not a connect request or an interrupt * 

* message, close the network and exit. If an interrupt * 

* message is in the mailbox (MLTYP = 2), simply issue * 

* a new GNDNT. * 

* • * 
***************************************************************** 



BllO-WAIT. 

CALL "WAITNT" USING 
INDX 
lOSTl 
I0ST2. 

IF INDX = 2 GO DIOO-INQREC. 
IF lOSTATl (1) NOT = 1 GO ClOO-CLOSNET . 
IF MLTYP NOT < 3 GO ClOO-CLOSNET. 
IF MLTYP = 2 GO BIOO-NETDAT. 

********************************************************** 

* 

A connect request is in the mailbox. Accept the * 

request to establish a logical link. If the call * 

completes unsuccessfully, issue a new GNDNT. * 

* 

********************************************************** 



CALL "ACCNTW" USING 
ACCLUN 
lOST 
MLBOX. 

IF lOSTAT (1) NOT = 1 GO BIOO-NETDAT. 



***************************************************************** 

* * 

* Pick up the data from the transmitting task. Issue * 

* a new GNDNT and wait for completion. * 

* * 
***************************************************************** 



CALL "RECNT" USING 
ACCLUN 



(continued on next page) 
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I0ST2 
RECSIZ 
RECBUF . 
GO BIOO-NETDAT. 

***************************************************** 

* * 

* A disconnect or abort was received. Deaccess the * 

* network and exit. * 

* * 
***************************************************************** 

ClOO-CLOSNET. 

CALL "CLSNTW". 
GO GIOO-END. 

***************************************************************** 

* * 

* An inquiry was received. Increment the message * 

* count. If the call completed unsuccessfully, send * 

* an interrupt message containing the message number * 

* in which the error occurred. * 

* * 
***************************************************************** 

DIOO-INQREC. 

ADD 1 TO NUMMES. 

IF I0STAT2 (1) = 1 GO ElOO-SEND. 
MOVE NUMMES TO INTMES. 
CALL "XMINT" USING 

ACCLUN 

lOST 

INTSIZ 

INTMES. 
GO FIOO-REC. 

***************************************************************** 

* * 

* Send data to the task. * 

* * 
***************************************************************** 

ElOO-SEND. 

CALL "SNDNTW" USING 
ACCLUN 
lOST 
SNDSIZ 
SNDDAT . 

***************************************************************** 

* * 

* Issue a new RECNT and wait for completion. * 

* * 

***************************************************************** 
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FIOO-REC. 

CALL "RECNT" USING 
ACCLUN 
I0ST2 
REGS I Z 
RECBUF . 
GO BllO-WAIT. 
GIOO-END. 

DISPLAY "COBREC — END OF EXECUTION". 
STOP RUN. 
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3.8.21 BASIC-PLUS-2 Intertask Communication Programming Examples 

The following two programs are examples of BASIC-PLUS-2 intertask communi- 
cation. They are cooperating tasks. BASTRN is a transmit task; BASREC is a 
receiver task. 

These examples are included in your tape or disk kit. 
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3.8.21 .1 Transmit Example 



The following program, BASTRN, accesses the network, connects to BASREC, 
transmits inquiries to BASREC, and processes responses from BASREC. When the 
program completes sending inquiries, it disconnects the link, stops accessing the 
network, and exits. 

Copyright (C) 1983, 1985, 1986, 1987 by 
Digital Equipment Corporation, Maynard, Mass. 



This software is furnished under a license and may be used and copied 
only in accordance with the terms of such license and with the 
inclusion of the above copyright notice. This software or any other 
copies thereof may not be provided or otherwise made available to any 
other person. No title to and ownership of the software is hereby 
transferred. 

The information in this software is subject to change without notice 
and should not be construed as a commitment by Digital Equipment 
Corporation. 

Digital assumes no responsibility for the use or reliability of its 
software on equipment which is not supplied by Digital. 



10 ! ! ! ! ! ! & 

!!! BASTRN. B2S - Transmit inquiries to BASREC and !!! & 

! ! ! process responses ! ! ! & 

! ! ! ! ! ! & 

!!! To task build, edit the task build command file !!! & 

!!! and the ODL file created by the build. !!! & 

! ! ! ! ! ! & 

! ! ! >Add the 1 ine ! ! ! & 

! ! ! ACTFIL=4 ! ! ! S. 

!!! to the task build command file. !!! & 

! ! ! ! ! ! S. 

! ! ! >Append ! ! ! & 

! ! ! -NETLIB ! ! ! & 

!!! to the USER: line of the ODL file. !!! & 

! ! ! ! ! ! & 

! ! ! >Add the line ! ! ! & 

!!! NETLIB: . FCTR LB : [ 1 , 1 ] NETFOR/LB !!! & 

! ! ! to the ODL file. ! ! ! & 

!!! Define array constants !!! & 

DIM I0ST%(1%) ,MSTAT%(2%) iDefine array elements & 

\ ERRMES$=STRING$(2%,0%) IDefine max string length & 
\ CONBLK$=STRING$(72%,0%) ! STRING$ ( LENGTH, ASCII VALUE) & 

\ RECBUF$=STRING$(10%,0%) ! & 
\ SNDBUF$=STRING$(50%,0%) ! 

20 INPUT "Node-name <MASTER>" ; NDNAM$ \ IF NDNAM$ = ''" THEN & 

NDNAM$= "MASTER" ELSE IF LEN(NDNAM$ ) >6% THEN & 

PRINT "Node-name too long, please re-enter" & 
\ PRINT \ GOTO 20 



(continued on next page) 
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30 INPUT "Receive task-name <RECVER>" ;TSKNAM$ \ IF TSKNAM$="" & 

THEN TSKNAM$="RECVER" ELSE IF LEN(TSKNAM$) >6% THEN & 

PRINT "Task-name too long, please re-enter" & 
\ PRINT \ GOTO 30 

40 ! ! ! Define constants ! ! ! ■ & 

IMMED%=-1% iSet IMMED% to true for GNDNTW & 

\ 0PNLUN%=1% ! Network OPNNT LUN & 

\ C0NLUN%=2% !CONNT LUN for the logical link & 

\ XMITS%=20% !The number of inquiries & 

! to send to the remote node & 

\ SNDSIZ%=50% !The size of the messages to & 

! send to the remote node & 

\ RECSIZ%=10% !The size of the messages to & 

! receive & 

\ NDNAM.LEN%=LEN<NDNAM$) 'Length of the node-name & 
\ TSKNAM.LEN%=LEN(TSKNAM$) ! Length of the task-name 

50 !!l*Access the network !!! & 

CALL OPNNTW BY REF ( OPNLUN% , I OST% ( ) , MSTAT% ( ) ) & 

\ IF IOST%{0%)=1% THEN 60 !If successful, build the & 

! connect block & 

ELSE PRINT "Network OPEN failed, IOST=" ; IOST% ( 0% ) ; IOST% ( 1% ) & 

\ GOTO 160 !Open failed. Print the status & 

! block and exit 

60 !!! Build a Format 1 connect block !!! & 

CALL BFMTl BY REF ( STAT% , CONBLK$ , NDNAM. LEN% , NDNAM$ & 

,DUMMY%,TSKNAM.LEN%,TSKNAM$) & 

\ IF STAT% THEN 70 ELSE !If success go on & 

PRINT "Error building connect block" & 

!Else type out an error message & 
\ GOTO 150 ! and exit 

70 ! ! ! Connect to the task on the remote node ! ! ! & 

CALL CONNTW BY REF (CONLUN% , IOST% ( ) , CONBLK$ ) & 

\ IF IOST%(0%)=1% THEN 80 !If success, tell it & 

ELSE PRINT "Connect Fail: IOST=" ; IOST% ( 0% );","; IOST% ( 1%) & 

!Else print status block & 
\ GOTO 150 !Else print status block and exit 

80 PRINT "Link enabled" !Print connect confirmation & 

! to network 

90 ! ! ! Send and receive messages to and from the remote node ! ! ! & 
FOR MESNUM%=1% TO XMITS% 

100 !!! First get any error messages sent from the other ! ! ! & 

! ! ! side via interrupt messages ! ! ! & 

IF MSTAT%(0%)=0% THEN 110 !If MSTAT% ( 0% ) =0% no messages & 

! are there & 

ELSE CALL GNDNTW BY REF ( IOST% ( ) ,MLTYP% , 2% , ERRMES$ & 

,DUMMY%, IMMED%,2%) !Get the message & 

\ IF IOST%(0%)<>1% THEN 110 ! I f we couldn't get message & 
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! just ignore it & 
ELSE PRINT "Error on inquiry #" ; ASCI I (LEFT (ERRMES$ , 1% ) ) 

IPrint out the message 

110 !!! Send the inquiry !!! & 

CALL SNDNTW BY REF ( CONLUN% , IOST% ( ) , SNDSI Z% , SNDBUF$ ) & 
\ IF IOST%(0%)=1% THEN 120!If success continue & 

ELSE PRINT "Error on inquiry during send: ";MESNUM% & 

lOtherwise type out an error i 
\ GOTO 130 Imessage and start a new message 

120 !!! Receive the response from the remote node !!! & 

CALL RECNTW BY REF ( CONLUN% , IOST% ( ) , RECSI Z% , RECBUF$ ) & 

\ IF IOST%(0%)=1% THEN 130! If success continue & 

ELSE PRINT "Error on inquiry during receive: ";MESNUM% & 

lOtherwise type out an & 
! error message 

130 NEXT MESNUM% ! End of loop 

140 !!! Disconnect the link !!! & 

PRINT "Link disabled" IPrint out disconnect message & 

\ CALL DSCNTW BY REF ( CONLUN% , IOST% ( ) ) 

150 ! ! ! Come here to deaccess the network and exit ! ! ! & 

CALL CLSNTW 

160 PRINT "End of execution" & 

\ END 
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3.8.21.2 Receive Example 

BASREC receives inquiries from BASTRN. It returns any errors to BASTRN as 
interrupt messages, which BASTRN displays on the terminal. 



Copyright (C) 1983, 1985, 1986, 1987 by 
Digital Equipment Corporation, Maynard, Mass. 



This software is furnished under a license and may be used and copied 
only in accordance with the terms of such license and with the 
inclusion of the above copyright notice. This software or any other 
copies thereof may not be provided or otherwise made available to any 
other person. No title to and ownership of the software is hereby 
transferred. 

The information in this software is subject to change without notice 
and should not be construed as a commitment by Digital Equipment 
Corporation. 

Digital assumes no responsibility for the use or reliability of its 
software 6n equipment which is not supplied by Digital. 



10 ! ! ! ! ! ! Sc 

!!! BASREC. B2S - Receive inquiries from BASTRN and !!! & 

! ! ! send back responses ! ! ! & 

! ! ! ! ! ! & 

!!! To task build, edit the task build command file J!! & 

!!! and the ,ODL file created by the build. !!! & 

! ! ! ! ! ! & 

! ! ! >Add the 1 ine ! ! ! & 

! ! ! ACTFIL=4 ! ! ! & 

!!! to the task build command file, !!! & 

! ! ! ! ! ! & 

! ! ! >Append ! ! ! & 

! 1 ! -NETLIB 1 ! ! & 

!!! to the USER: line of the DDL file. >!! & 

! ! ! ! ! ! & 

! ! ! >Add the 1 ine ! ! ! & 

!!! NETLIB: . FCTR LB : [ 1 , 1 ]NETFOR/LB !!! & 

! ! ! to the ODL file. ! ! ! & 

!!! Initialize constants !!! & 

DIM MSTAT%(2%) , I0ST%(1%) , I0ST1%(1%) , I0ST2%(1%) & 
\ INTMES$=STRING${2%,0%) IDefine max length of strings & 

\ MLBX$=STRING${98%, 0%) ! STRING$ { LENGTH , ASCI I VALUE) & 

\ RECBUF$=STRING$(50%,0%) ! & 
\ SNDDAT$=STRING$(10%,0%) ! 

20 ! ! ! More constants ! ! ! & 

0PNLUN%=1% ! Network OPNNT LUN & 

\ ACCLUN%=2% !Accnt LUN for logical link & 

\ RECSIZ%=50% !Size of data buffer to be & 

! received & 

\ INTSIZ%=2% !Size of interrupt data buffer & 

! to send & 
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\ NUMMES%=0% INumber of messages received & 

\ INDEX=0% [Receive completion flag & 

\ SNDSIZ%=10% INumber of bytes to send back 

30 ! ! ! Access network ! ! ! & 

CALL OPNNTW BY REF ( OPNLUN% , I OST% ( ) , MSTAT% ( ) ) & 

\ IF IOST%(0%)<>1% THEN 140 !If failure just exit & 

ELSE IF MSTAT%(0%)=0% THEN 90! If nothing on mailbox & 

! just close and exit 

40 CALL GNDNT BY REF(I0ST1%( ) ,MLTYP%,98%,MLBX$) & 

! Issue Get Network Data 

50 CALL WAITNT BY REF(INDEX%,I0ST1%(),I0ST2%()) & 

IWait for a completion & 

\ IF INDEX%=2% THEN 100 !If INDEX%=2% then a receive & 

! has been completed 

60 !!!. Network data has been received !!! & 

IF IOST1%(0%)<>1% THEN 90 !If GNDNT failed, just & 

! close and exit & 

ELSE IF MLTYP%>=3% THEN 90 !If MLTYP%>=3% then link has & 

• been broken & 

ELSE IF MLTYP%=2% THEN 40 !If MLTYP%=2% we've received & 

! an interrupt message. Just & 

! issue a GNDNT 

70 !!! We've received a connect request - issue an accept !!! & 

CALL ACCNTW BY REF( ACCLUN% , IOST% ( ) ,MLBX$ ) & 
\ IF IOST%(0%)<>1% THEN 40 !If failure issue a new GNDNT 

80 ! ! ! Issue a receive to pick up data ! ! ! & 

CALL RECNT BY REF ( ACCLUN% , I0ST2% ( ) , RECS I Z% , RECBUF$ ) & 

\ GOTO 40 ! Issue a new GNDNT and & 

! wait for the completion 

90 ! 1 ! We come here upon receiving a disconnect or abort ! ! ! & 

CALL CLSNTW iDeaccess the network & 

\ GOTO 140 ! and exit 

100 !!! We come here if we receive an inquiry !!! & 

NUMMES%=NUMMES% + 1% '.Increment the message count & 

\ IF IOST2%(0%)=1% THEN 120 !If IOST2%(0%)=1 all's okay 

110 III If there was an error, send back an interrupt message !!! & 

! ! ! with message number ! ! ! & 

INTMES$=CHR$(NUMMES%)+CHR$(0%) !Send the message number & 

\ CALL XMINT BY REF(ACCLUN%, IOST%( ) , INTSIZ%, INTMES$) & 

\ GOTO 130 !Go issue a new receive & 

120 ! ! ! Here the user can look at the data received in RECBUF$ ! ! ! & 

!!! and respond by replacing the requested information !!! & 

! t ! into SNDDAT$ ! ! ! & 

! ! ! Send back the data and issue a RECNT ! ! ! & 

CALL SNDNTW BY REF ( ACCLUN% , IOST% ( ) , SNDSI Z% , SNDDAT$ ) 



(continued on next page) 
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130 CALL RECNT BY REF(ACCLUN%, I0ST2%( ) ,RECSIZ%,RECBUF$) & 

\ GOTO 50 !Wait for a completion 

140 ! ! I Exit program ! I ! & 

PRINT "End of program execution" & 
\ END 
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3.9 Remote File Access 

This section contains descriptions and usage guidelines specific to the remote file 
access calls listed alphabetically in Table 3-3. 

Table 3-3: Remote File Access Calls 



Call 


Function 


ACONFW 


Set record and file access options 


ATTNFW 


Set extended attributes 


CLSNFW 


Close a file 


DELNFW 


Delete a file 


EXENFW 


Execute a file 


GETNFW 


Read a single record 


OPANFW 


Open and append a sequential file 


OPMNFW 


Open and modify a sequential file 


OPRNFW 


Open and read a sequential file 


OPUNFW 


Open and update a sequential file 


OPWNFW 


Create, open, and write a sequential file 


PRGNFW 


Discard an open file 


PUTNFW 


Write a record to a file 


RENNFW 


Rename a file 


SPLNFW 


Open, write, and print a file 


SUBNFW 


Open, write, and execute a file 



These calls are implemented by subroutines. The network open call, OPNNT[W], 
and the network close call, CLSNT[W], are also used in remote file access opera- 
tions. You must always issue OPNNT[W] first because OPNNT[W] lets your task 
access the network. Issue CLSNT[W] last to close your task's access to the net- 
work. 
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9.1 Opening Files 

The following nine subroutines open files: 

ACONFW Specifies record and file access options before performing a spe- 
cific file operation. 

ATTNFW Specifies extended attributes before performing OPWNFW, 

SPLNFW, SUBNFW, OPRNFW, OPANFW, andRENNFW calls. 

OPRNFW Opens an existing file for reading, beginning with the first record. 

OPANFW Opens an existing file and appends records to the end of the file. 

OPMNFW Opens an existing file for record modification. 

OPUNFW Opens an existing file for record update. 

OPWNFW Creates and opens a file, then writes records to it, beginning with 
the first record position. 

SPLNFW Performs the same function as OPWNFW and then prints the file. 

SUBNFW Performs the same function as OPWNFW and then executes the 
file. 

Each open subroutine creates a DECnet logical link to the node where the file 
resides and then creates and opens the file. You must use the same LUN to open, 
write, and close the file. This LUN must not be in use. 

Issue an ATTNFW or ACONFW call immediately before OPRNFW, OPANFW, and 
RENNFW calls to specify additional attributes to be returned after the open opera- 
tion completes. 

9.2 Performing File Operations 

The following subroutines perform file operations: 

EXENFW Executes a remote file. 
DELNFW Deletes a remote file. 
RENNFW Renames a remote file. 
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3.9.3 Performing Record Operations 

The following subroutines perform record operations: 

GETNFW Reads a record from a remote file. 
PUTNFW Writes a record to a remote file. 

3.9.4 Closing Files and Completing Calls 

When you complete a file access operation, use CLSNFW to close the file. To 
clean up errors before closing the file, use PRGNFW for your close operation. 
Both CLSNFW and PRGNFW disconnect the logical link and free the logical unit 
number for use. If you do not perform a close operation before attempting a 
CLSNT[W] to stop accessing the network, or if a network abort occurs while the 
file is open, the network closes the file. However, all data may not have been 
transferred successfully. 

Remote file access calls are synchronous and do not return to the user until an 
operation completes. 

3.9.5 Setting Task Build Parameters 

DECnet-RSX uses network file access routines (NFARs) as the local node interface 
to access remote files for user applications. At task build time you can override 
defaults to tailor these NFARs for a particular application. You can set the follow- 
ing task build parameters: 

■ Event flags .TREE and .RCEF. (The defaults are 17 and 18, respectively.) 

■ Buffering level. (The default is 2 .) 

■ Maximum record size. (The default is 256. bytes.) 

■ Buffer space allocation. (There is no default.) 

3.9.5.1 Setting Event Flags 

The network file access routines (NFARs) require the exclusive use of two event 
flags. The default event flags are 17(.TREF) and 18(.RCEF). To override these 
defaults, issue the following commands in the task builder command file: 

GBLDEF=.TREF: value 

GBLDEF= . RCEF : value 
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The value variable specifies an event flag and must be in the form of an octal inte- 
ger from 1 to 200 (octal). Event flags 33. through 64. are global flags. 

3.9.5.2 Setting Buffering Level 

The NFARs can be configured for multibuffering to improve throughput. This 
requires more internal buffering space than the default buffering level of 2. To 
override this default, issue the following command in the task builder command 
file: 

GBLDEF=$NFNMB : buffering-level 

The buffering-level variable specifies an integer from 1 to 4. For an RSX or IAS 
remote system, use the buffering level that the remote system uses. Ask the sys- 
tem manager for the information. 

3.9.5.3 Setting Maximum Record Size 

The internal buffers used by the NFARs must be large enough to hold the largest 
data record in the remote file. The default maximum record size is 256 bytes. To 
override this default, include the following command in the task builder com- 
mand file: 

GBLDEF=$NFRSZ : record-size 

The record-size variable specifies an octal value. For an RSX or IAS remote sys- 
tem, use the record size that the remote system uses. 

In calculating the maximum record size, note that certain file types require extra 
bytes, as follows: 

■ ASCII files require 2 extra bytes for carriage return and line feed characters 
that are appended to each ASCII record. 

■ Sequenced variable length records require 2 extra bytes for the sequence 
number included with each record. 

■ ASCII files with sequenced variable length records require 4 extra bytes. 
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3.9.5.4 Setting Buffer Space Allocation 

The NFARs allocate buffer space from the file storage region used by the File Con- 
trol System (PCS- 11). This space is allocated in the P-section $$FSR1. Your task 
must include the module NFAFSR from the NETFOR object library. Be sure to 
enter the following line in the task build command as an input file: 

[1,1] NETFOR/LB : NFAFSR 

Use the following formula to calculate the required buffer space for performing 
remote file access: 

((($NFRSZ + 14.)*($NFNMB + 1)) + 64 .)* (max-rem-files) + (space.* <max-loc-files>) 
where 

space is the space overhead per local file. 

max-rem-files is the maximum number of remote files that can be open con- 
currently. 

max-loc-files is the maximum number of local files that can be open con- 
currently. 

The space variable for local file overhead value is 5 12. if your language uses FCS- 
1 1 . If your language uses a different file system, refer to its documentation for the 
exact value. 

At task build time, use the value that you calculated with the formula to extend 
the file storage region. Include the following command in the task builder com- 
mand file, entering the value in octal bytes: 

EXTSCT=$$FSR1 : value 

3.9.5.5 Using the Task Build Procedure 

A task must link to NETFOR. OLE to use the DECnet-RSX remote file access capa- 
bilities. Edit the ODL file that the compiler created. The following example shows 
a task using the CMD and ODL files. This task uses the defaults for the buffer size 
($NFRS2), the number of buffers ($NFNMB), and only one link. The underlined 
items indicate the required edits for the task builder to include remote file access 
capabilities in the task. Boldface items are required for network access. 
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FORTRAN Example: 



FILES.CMD {.B SY:FILES,SY:FILES/-SP=SY:FILES.LB: [IjljE-iPOTS 
LB: [1,1]NETF0R/LB, NETF0R/LB :NFAFSR 

/ 

EXTSCT=$$FSR1:2700 
// 



You enter: 



MCR>TKB e> FILES RED 

COBOL Example: 

FILES.CMD 

SY : FILES , SY : FILES/-SP=SY : FILES/MP 

EXTSCT=$$FSR1:2700 

// 

FILES. ODL 



MERGED ODL FILE CREATED ON 26-FEB-82 AT 16:5-4:32 

COBOL STANDARD ODL FILE GENERATED ON 26-FEB-82 16:46:29 

COBOBJ=FILES.OBJ 



LB: [1 , 1] NETFOR/LB- NETFOR/LB : NFAFSR 

SY: [200, 200] FILES 

LB: [1,1]C0BLIB/LB 

CB0BJ$-CB0TS$-LIBR1 

OBJRT$ 



; COBMAIN 




LIBRl: 


.FCTR 


CBOBJ$ : 


.FCTR 


CBOTS$: 


.FCTR 


OB JRT$ : 


.FCTR 




.ROOT 




.END 



You enter: 



MCR>TKB e FILES BET) 



BASIC-PLUS-2 Example: 

FILES.CMD 

SY : FILES/CP/FP , FILES/-SP=SY : FILES/MP 
UNITS = U 
ASG = TI:13 

ASG = SY:5:6:7:8:9:10:11:12 

EXTSCT = $$FSR1:2700 

// 



FILES. ODL 

.ROOT 

USER: .FCTR 
LIBR: .FCTR 
NETLIB: .FCTR 

g'LB:[l,l]BP2ICl 
«'LB:[1,1]RMS11X 
.END 



BASIC2-RMSR0T-USER,RMSALL 

SY:FILES-NETLIB 

LB:[1,1]BP20TS/LB 

LB: [1, 1] NETFOR/LB-NETFOR/LB : NFAFSR 



You enter: 

MCR>TKB SPILES (REH 
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3.9.6 Using ASCII Zero (ASCIZ) Strings 



Some of the network file access subroutines require that you provide one or more 
arguments in the CALL statement as ASCIZ strings. An ASCI2 string is a string of 
ASCII characters terminated by a binary (0). 

You can create an array/numeric data item, store the string in the array /numeric 
data item, and then set the last element to zero (0). 

FORTRAN Example: 

DIMENSION IFILE (12) 

DATA IFILE/'DK' , '0: ' , ' [!' , ' ,4' , ']C' , 

•N','TR','0L','.A','LG',';2'/ 

IFILE(12)=0 

You then specify the array name in the CALL statement: 

CALL OPRNFW { lun, Status, node, ,IF11I.) 

COBOL Example: 

01 NULLl PIC 9 COM? VALUE 0. 
01 NULLS REDEFINES NULLl. 
03 NULL OCCURS 2 TIMES PIC X(l). 
01 IFILE PIC X(23) VALUE "DKO: [200,200,]NAME.CBL;1" 

STRING IFILE 
NULL (1) 

INTO IDENT. 

You then specify the string in the CALL statement: 

CALL "OPRNFW" USING lun, status, node, ident. 

BASIC-PLUS-2 Example: 

IFILE$="DKO : [200 , 200] NAME . B2S ; 1"+CHAR$ ( 0$) CHAR$ ( 0^ ) 

You then specify the array name in the CALL statement: 
CALL OPRNFW BY REF {lun%,status%{) ,node%,ident%,ifile%) 
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3.9.7 Common Argument Definitions for Remote Fiie Access Cails 

This section defines the common arguments for remote file access calls. The gen- 
eral group defines arguments common to all languages, and three individual 
groups define arguments specific to FORTRAN, COBOL, and BASIC-PLUS-2. 

GENERAL 

■ lun 

is an integer variable or constant that specifies the logical unit number of the 
logical link created for a specific file access operation. 

■ node 

specifies the name of the target node. It is a 1- to 7-element array /string that 
ends with a binary and contains a 1- to 6-character ASCIZ string. 

■ ident 

contains three successive ASCIZ strings: the user ID, password, and account 
number necessary to access remote node files. It is a 1- to 72. -element ASCIZ 
array. 

Enter a null value (0) for each item not required by the remote node or each 
item previously entered. For example, you may have already entered the 
required information in an alias node name block. 

■ ifile 

is a byte array /string containing a variable length ASCIZ string that contains 
the file specification for a file access operation. Be sure to use the remote 
node's file specification syntax. 

FORTRAN 

■ References to integers imply single-precision integer values. 

■ status 

specifies an array that contains completion status information on return 
from the call. This 2 -element single-precision integer array contains the fol- 
lowing values when the call completes: 

status{\) returns a completion code. A positive 1 indicates success; 

a negative integer indicates an error. Appendix C lists and 
describes the error codes. 
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status(2) depends on the contents of the first status word. Refer to 

Appendix C. 

COBOL 

■ For DECnet COBOL, the logical unit number 1 is a reserved number and 
should never be assigned for the lun argument. 

■ status 

specifies an elementary numeric data item that contains completion status 
information on return from the call. This elementary numeric data item con- 
tains the following values when the call completes: 

status{\) returns a completion code. A positive 1 indicates success; 

a negative integer indicates an error. Appendix C lists and 
describes the error codes. 

status(2) depends on the content of the first status word. Refer to 

Appendix C . 

BASIC-PLUS-2 

■ status%() 

specifies an array that contains completion status information on return 
from the call. This 2 -element integer array contains the following values 
when the call completes: 

status%(0) returns a completion code. A positive 1 indicates success; 

a negative integer indicates an error. Appendix C lists and 
describes the error codes. 

status%(l) depends on the contents of the first status word. Refer to 

Appendix C. 
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ACONFW 

(Set Access Options) 

3.9.8 ACONFW — Set Access Options 
Use: 

Call ACONFW before a specific file operation to specify record and file access 
options to apply to that file operation. These options remain in effect until the file 
is closed. 

Formats: 

FORTRAN: CALL ACONFW (lun, status, [fac],[shr],[fop]) 
COBOL: CALL "ACONFW" USING lun, status, [fac],[shr], [fop]. 
BASIC: CALL ACONFW BY REF (lun%,status%(), [fac%],[shr%],[fop%()]) 

Arguments: 
lun 

specifies the logical unit number of the logical link assigned to the file opera- 
tion for which to set options. 

* status 

specifies completion status on return from ACONFW. See the definitions for 
your language in Section 3 9 7. Refer to Appendix C for error code descrip- 
tions. 

fac 

specifies the operations to allow during file access. Use this argument only 
for open and create operations. The fac value overrides the type of access 
that the OPatNFW call specifies. Valid values are: 



1 Put access 

2 Get access (default) 
4 Delete record access 
10 Update record access 
20 Truncate file access 
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40 Block I/O 

41 Block I/O write 

42 Block I/O read 

shr 

specifies the file sharing to be allowed by the remote system. Use this argu- 
mem only for open and create operations. The actual functioning depends 
on the remote system's capabilities. Valid values are: 



1 


Put access 


2 


Get access (default) 


4 


Delete record access 


10 


Update record access 


100 


No access to others 


fop 





specifies a 3-word array for file-processing options that open, create, and 
close operations will use. To specify a fop value for close operations, first 
open the file, and then make the ACONFW call, because the open call over- 
writes the current value. Valid values are: 

First word: 

400 Create contiguous file 

1 000 Supersede existing file 

4000 Create temporary file 

1 0000 Create temporary file and mark for delete 

Second word: 

40 Maximize version number on create 

100 Spool on close 

400 Execute on close 

1000 Delete on close 
20000 Truncate on close 

Completion of open/create operations returns: 

First word: 

40 File is a directory (system dependent) 

100 File is locked 

400 File is contiguous 
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ATTNFW 

(Set Extended Attributes) 

3.9.9 ATTNFW — Set Extended Attributes 
Use: 

Call ATTNFW to specify extended attributes to use with a create, open, or close 
file operation. You call ATTNFW immediately before the operation; the attri- 
butes are returned on completion of the operation. 



Call ATTNFW with the following operations: 



Operation 


Calls 


What ATTNFW Does 


Create 


OPWNFW 


Specifies additional attributes in creating the 




SPLNFW 


file. 




SUBNFW 




Open 


OPRNFW 


Specifies additional attributes to be returned 




OPANFW 


when opening the file. 




RENNFW 




Close 


CLSNFW 


Specifies a change-attributes-on-close 






sequence. 



Formats: 

FORTRAN: CALL ATTNFW (lun, status, [namesize],[name],[atb], 

[protblk] , [owner] , [dateblk]) 

COBOL: CALL "ATTNFW" USING lun, status, [namesize],[name],[atb], 

[protblk],[owner],[dateblk] . 

BASIC: CALL ATTNFW BY REF (lun%, status %i),[namesize%],[name$], 

[atb%{ )],\protblk%{)], 
[owner$],[dateblk%()]) 
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Arguments: 

lun 

specifies the logical unit number of the logical link for the file operation. 

* status 

specifies completion information on return from ATTNFW. See the defini- 
tion for your language in Section 3 9 7. Refer to Appendix C for error code 
descriptions. 

namesize 

specifies the maximum length of the array /string that can be returned to the 
resultant file specification. Use this single-word argument for open and cre- 
ate operations. 

* name 

specifies the array /string containing the resultant file name. This argument 
can be used for all operations. The returned file name is an ASCIZ string. 

* atb 

specifies a Files- 1 1 user file attributes block. When specifying create opera- 
tions, the user program is responsible for setting valid values because the 
NFARs do not check these values. 

NOTE 

If atb is specified, the ichar(2), ichar(5), and len 
arguments are ignored when used with open or 
create calls. Use the fields NF$ORG, NF$RAT, 
and NF$MRS, instead. 

When specifying create and open operations, atb returns a 10. -word block 
in the following format. 
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RECORD ATTR 


FILE ORG /REC FMT 


LONGEST RECORD LENGTH 


HIGHEST VBN ALLOCATED (high word) 




(low word) 


END-OF-FILE VBN 


(high word) 




(low word) 


FIRST FREE BYTE 


FIXED CTR SIZE 


BUCKET SIZE 


MAXIMUM RECORD SIZE 


DEFAULT EXTEND QUANTITY 



LKG-1 036-87 



For further information on the values of these fields, see the RSX-llM/M- 
PL US or Micro/RSX I/O Operations Reference Manual. 

* protblk 

specifies an array containing file protection information to be used as input 
for create and close operations, and returns information from create and 
open operations. The following format describes a 5 -word array. 
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FILE OWNER STRING SIZE 



SYSTEM PROTECTION MASK 



OWNER PROTECTION MASK 



GROUP PROTECTION MASK 



WORLD PROTECTION MASK 



LKG-1 037-87 

If the file owner size is 0, the owner string is not returned. 
The format of the protection masks is as follows-. 

Bit = Deny read access 

Bit 1 = Deny write access 

Bit 2 = Deny execute access 

Bit 3 = Deny delete access 

Bit 4 = Deny append access 

Bit 5 = Deny directory list access 

Bit 6 = Deny update access 

Bit 7 = Deny change protection access 

Bit 8 = Deny extend access 

If a word is set to -1 , that protection is not sent. 

* owner 

specifies an ASCIZ string/array identifying the file owner to use as input for 
create operations and for output from create and open operations. The first 
word of the protblk array must specify the maximum size of this string/ 
array. 

* dateblk 

specifies a 19-word array whose fields contain the file's revision number, 
creation and revision date and time, and/or expiration date. The date block 
menu specifies the fields in the block that create and close operations can get 
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values from, and create and open operations can return values to. Date block 
menu values are as follows: 

Bit = Revision number 
Bit 1 = Revision date and time 
Bit 2 = Creation date and time 
Bit 3 = Expiration date 

The date block fields contain Files- 1 1 time stamps. The time stamps are in 
ASCII and have the format ddmmmyyhhmmss, w^here mmm, the month 
abbreviation, is in uppercase letters. Leading zeros are included. This is the 
format of the date block. 



3-102 



DECnet-RSX Programmer's Reference Manual 



ATTNFW 



DATE BLOCK MENU 


REVISION NUMBER 


— 


REVISION DATE 


— 
— 












REVISION TIME 










— 


— 


CREATION DATE 


— 




CREATION TIME 






EXPIRATION DATE 




(not used) 







LKG-1 038-87 

For further information on the format of dates in a block, see the 
RSX-llM/M-PLUS or Micro/RSXI/O Operations Reference Manual. 
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CLSNFW 

(Close a File) 

3.9.10 CLSNFW — Close a File 
Use: 

Call CLSNFW to close a remote file. CLSNFW forces completion of all pending file 
operations, ensures that the file directory information is valid, and optionally 
modifies the attributes that the changeattr argument specifies. The logical unit 
number is freed when the CLSNFW call completes. 

Note that some systems do not let you change attributes on close. 
Formats: 

FORTRAN: CALL CLSNFW {lun, status, [changeattr]) 
COBOL: CALL "CLSNFW" USING lun, status, [changeattr]. 
BASIC : CALL CLSNFW BY REF (lun % ,status% ( ),[changeattr% ]) 

Arguments: 

lun 

specifies the logical unit number of the logical link to close. See the defini- 
tion in Section 3. 9. 7. Use the same LUN that the previous open call specified. 

* status 

specifies completion status information on return from CLSNFW. See the 
definition for your language in Section 3. 9. 7. Refer to Table C-1 in Appen- 
dix C for a complete code list. 

changeattr 

specifies attributes to change when this file closes. A previous ATTNFW call 
must specify these attributes either at open time or just before this call. Valid 
values are: 

2 Change protection 

4 Change dates and times 
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DELNFW 

(Delete a File) 

3.9.1 1 DELNFW — Delete a File 
Use: 

Call DELNFW to delete a remote file. 
Formats: 

FORTRAN: CALL DELNFW {lun, status, node, ident, if He) 
COBOL: CALL ' 'DELNFW' ' USING lun, status, node, ident, if He. 
BASIC: CALL DELNFW BY RE¥ (lun% ,status%( ),node$,ident$,ifile$) 

Arguments: 

lun 

specifies the logical unit number of the logical link to delete. See the defini- 
tion in Section 3 9 7. 

* status 

specifies completion status information on return from DELNFW. See the 
definition for your language in Section 3 .9.7. Refer to Table C-1 in Appen- 
dix C for a complete code list. 



node 

specifies the name of the node for the file to delete. See the definition in Sec- 
tion 3.9.7. 



ident 

is an array /string containing explicit access control information. See the defi- 
nition in Section 3. 9. 7. 



ifile 

specifies an ASCIZ string containing the file specification for the file to be 
deleted. See the definition in Section 3 .9 7. 
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EXENFW 

(Execute a File) 

3.9.12 EXENFW Execute a File 
Use: 

Call EXENFW to submit an existing remote file to the batch or command file pro- 
cessor. The remote file is not deleted after this call completes. 

Formats: 

FORTRAN : CALL EXENFW {lun, status, node, ident, if He) 

COBOL: CALL "EXENFW" USING lun, status, node, ident, if He. 

BASIC: CALL EXENFW BY REF {lun% ,status%{),node% ,ident$ ,ifile$) 

Arguments: 

lun 

specifies the logical unit number of the logical link to execute. See the defini- 
tion in Section 3 9. 7. 

* status 

specifies completion status information on return from EXENFW. See the 
definition for your language in Section 3. 9. 7. Refer to Table C-1 in Appen- 
dix C for a complete code list. 

node 

specifies the name of the node for the file to execute. See the definition in 
Section 3.9. 7. 

ident 

is an array /string containing explicit access control information. See the defi- 
nition in Section 3 9 7. 

ifile 

specifies an ASCIZ string containing the file specification for the file to be 
executed. See the definition in Section 3 9 7. 
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GETNFW 

(Read a Single Record) 

3.9. 1 3 GETNFW — Read a Single Record 

Use: 

Call GETNFW to read a record from a file. The FORTRAN inarray or the COBOL 
or BASIC instring argument specifies the array/string in which to store the 
record. Each successive GETNFW call reads the record into the same array /string, 
overlaying any previous record. The previous record is no longer available in the 
user record storage area. 

The optional rac argument specifies the record access mode. If you omit this 
argument, the default access mode is sequential file transfer by records. The 
records are read sequentially from the first record in the file. 

If you include a rac argument specifying random access, you must include the 
keyptr argument to specify the record to read. 

If an error occurs while a file is being read, the logical link is maintained. You 
must call CLSNFW to close the file. 

Formats: 

FORTRAN: CALL GETNFW {lun, status, inbytes, inarray, 

[seqno] , [rac] , [keyptr] , [rop]) 

COBOL: CALL "GETNFW" USING lun, status, incbars, 

instring, [seqno] , [rac] , [keyptr] , [rop] . 

BASIC: CALL GETNFW BY REF (lun% ,status%( ),inchars%,instring$ , 

[seqno%],[rac%],[keyptr%( )],[rop%( )]) 

Arguments: 

lun 

specifies the logical unit number of the logical link created for reading your 
records. See the definition in Section 3 -9. 7. Use the same LUN you assigned 
in the OPRNFW, OPMNFW, or OPUNFW call. 
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status 

specifies completion status information on return from GETNFW. The sec- 
ond word contains the byte count length of the record returned. See the def- 
inition for your language in Section 3 9 7. Refer to Table C-1 in Appendix C 
for a complete code list. 

mbytes linchars 

specifies the length in bytes/characters of inarray Unstring. It is an integer 
variable or constant. The actual length of the record read is returned in the 
second status word. 

inarray Unstring 

specifies the array /string that contains the record to read from the file. If the 
record size is larger than the integer you specified in inhytes linchars, the 
balance of the record is lost. 

seqno 

specifies the sequence number for the record to read from the file. You must 
specify this integer variable for sequenced variable length records. If the 
record type is not sequenced variable length (or in RMS terms, variable with 
fixed control, VFC) the seqno argument is ignored. Be sure to specify the 
record type in the ichar argument of an open call. 

rac 

specifies the mode to use in accessing the file. If you omit the rac value, the 
default access mode is sequential file transfer by records. Sequential file 
transfer modes (3 and 5) cause any rac value in a subsequent GETNFW or 
PUTNFW calls to be ignored until you close the file. If the file is open for 
record access, the rac argument can be one of the following: 



Sequential by record 

1 Random by relative record number (RRN) 

2 Random by record file address (RFA) 

3 Sequential file transfer by records (default) 

If the file is open for block access, the rac argument can be one of the fol- 
lowing: 

4 Random blocks by virtual block number (VBN) 

5 Sequential file transfer by blocks 
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keyptr 

specifies the record. The length is assumed from the rac argument value. 



RAC 


Key 


1 


Two- word binary value of RRN 




Low-order word first 


2 


Three-word binary RFA 




Low-order word first 


4 


Two- word binary value of VBN 




Low-order word first 


rop 





specifies record processing options. Valid values are: 

1 Position to EOF 

4 Update if existing record 
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OPANFW, OPMNFW, OPRNFW, OPUNFW 

(Open a File for Appending, l\/lodifying, Reading, Updating Records) 

3.9.14 OPANFW — Open a File for Appending Records 
OPMNFW — Open a File for i\/lodifying Records 
OPRNFW — Open a File for Reading Records 
OPUNFW ~ Open a File for Updating Records 

Use: 

Call one of the following subroutines to open an existing file: 

Call OPANFW to open a sequential file for appending records. 
Call OPMNFW to open and modify a sequential file. 
Call OPRNFW to open a sequential file for reading records. 
Call OPUNFW to open and update a sequential file. 

For information on OPWNFW (Create and Open a File for Writing Records), refer 
to Section 3 9. 18. 

Formats: 

FORTRAN: CALL 

COBOL: CALL 
BASIC: CALL 



rOPANFW^ 
OPMNFW I 
OPRNFW I 
OPUNFW J 

^"OPANFW" 
"OPMNFW 
"OPRNFW" 
"OPUNFW" 

rOPANFW^ 
I OPMNFW 
1 OPRNFW 
^OPUNFW J 



{lun, Status, node, ident, if He, ichar, len , 
[iblock]) 



USING lun ,status,node, ident, if He, ichar, 
len, [iblock]. 



BY REF (lun% ,status%( ),node$ ,ident$ , 
ifile$ , ichar$ ,len % , [iblock]) 
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OPANFW, OPMNFW, OPRNFW, OPUNFW 



lun 

specifies the logical unit number of the logical link created for the OPANFW, 
OPMNFW, OPRNFW, or OPUNFW call. Use the same LUN for any succeed- 
ing PUTNFW, PRGNFW, or CLSNFW call. See the definition in Section 
3.9.7. 

* status 

specifies completion status information on return from OPANFW, 
OPMNFW, OPRNFW, or OPUNFW. See the definition for your language in 
Section 3.9.7. Refer to Table C-1 in Appendix C for a complete code list. 

node 

specifies the name of the node for the file to open. See the definition in Sec- 
tion 3.9.7. 

ident 

is an array /string containing explicit access control information. See the defi- 
nition in Section 3. 9. 7. 

ifile 

specifies an ASCIZ string containing the file specification for the file to open. 
See the definition in Section 3 -9. 7. 

* ichar 

is a 3 -element array /string. If the values you specify differ from those stored 
in the file, the stored values are used. When the open call completes, the 
ichar array /string contains the stored values. Check these values to see how 
the file was actually opened. Make sure you specify the appropriate ASCII 
letter code as defined in the following three fields: 

ichar{\) - Mode 

Letter Code Description 

A ASCII file 

I Binary image file 
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ichar{2) - Record Format 



Letter Code 



Description 



u 

F 
V 
S 
A 



Undefined format records 

Fixed length records 

Variable length records 

Sequenced variable length records (VFC) 

ASCII stream format 



ichar(3) - Carriage Control 



Letter Code 



Description 



F 
T 
N 
P 



FORTRAN carriage control 
Terminal carriage control 
No carriage control 
Print file VFC 



The following example displays one method for the /c/b^^r argument. In this 
example, ichar specifies the file to be opened as an ASCII file ('A'), with vari- 
able length records ('V'), and FORTRAN style carriage control ('F'). 

Example: 

BYTE ICHAR (3) 

DATA ICHAR/' A' , 'V , 'F'/ 

ICHAR PIC XXX VALUE "AVE". (COBOL) 

ICHAR$="AVF" (BASIC) 



is an integer variable that specifies record length. If the file has variable 
length records, enter the maximum record length. A null value (0) implies 
there is no maximum record length. 



len 
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* ihlock 

is an integer variable that returns the number of blocks currently allocated to 
the file. The values are described as follows: 

Entry Description 

+ n Number of noncontiguous blocks 

(where « = number of blocks) 

-n Number of contiguous blocks 

(where w = number of blocks) 
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PRGNFW 

(Discard an Opened File) 

3.9.1 5 PRGNFW ~ Discard an Opened File 

Use: 

Call PRGNFW to close a remote file because one or more errors occurred in the 
transfer. If the file was newly created by an OPWNFW, SPLNFW, or SUBNFW 
call, it is deleted. If the file existed previously and was just opened by an 
OPRNFW or OPANFW call, it is closed in its current state. 

Formats: 

FORTRAN: CALL PRGNFW {lun,status) 

COBOL: CALL "PRGNFW ' USING lun,status. 

BASIC : CALL PRGNFW BY REF {lun % ,stcitus% ( )) 

Arguments: 

lun 

specifies the logical unit number of the logical link to close. See the defini- 
tion in Section 3 9 7. Use the same LUN specified in the previous open call. 

* status 

specifies completion status information on return from PRGNFW. See the 
definition for your language in Section 3 . 9. 7. Refer to Table C-1 in Appen- 
dix C for a complete code list. 
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PUTNFW 

(Write a Single Record) 

3.9.16 PUTNFW — Write a Single Record 

Use: 

Call PUTNFW to write a record to a file. PUTNFW writes the indicated number of 
bytes/characters from the array/string you specify in the outarrayloutstring 
argument. 

The optional rac argument specifies the record access mode. If you omit this 
argument, the default access mode is sequential file transfer by records. The 
records are written sequentially beginning at the first record position unless the 
file was opened with an OPANFW call. In that case they are written after the last 
record. 

If a rac value specifies random access, the keyptr argument must specify the 
record position where the record is written. 

If a PUTNFW call returns an error, you can close the output file with either a 
PRGNFW or CLSNFW call or continue the write (PUTNFW) operation. 

Formats: 

FORTRAN: CALL PUTNFW {lun, status, outbytes,outarray, 

[seqno] , [rac] , [keyptr] , [rop]) 

COBOL: CALL "PUTNFW" USING lun,status,outchars,outstrmg, 

[seqno] , [rac] , [keyptr] , [rop] . 

BASIC: CALL PUTNFW BY REF {lun% ,status%(),outchars% ,outstring% , 

[seqno%],[rac%],[keyptr%()],[rop%( )]) 

Arguments: 

lun 

specifies the logical unit number of the logical link created for writing a sin- 
gle record. See the definition in Section 3 . 9. 7. Use the same LUN you 
assigned in the OPANFW, OPMNFW, OPUNFW, SPLNFW, SUBNFW, or 
OPWNFW call. 
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status 

specifies completion status information on return from PUTNFW. See the 
definition for your language in Section 3.9.7. Refer to Table C-1 in Appen- 
dix C for a complete code list. 

outbytesloutchars 

specifies the number of bytes/characters to be written to the file from the 
outarrayloutstring argument. This integer variable or constant must be 
equal to or less than the maximum record length you specified in the open 
call. If data overrun occurs, the remaining bytes are lost. 

outarrayloutstring 

is the name of the array /string that contains the record to be written to the 
file. 

seqno 

specifies the sequence number of the record to be written. You must specify 
this integer variable or constant for sequenced variable length records. If the 
record type is not sequenced variable length (or in RMS terms, variable with 
fixed control, VFC), the seqno argument is ignored. Remember to specify the 
record type in the ichar argument of an open call. 

rac 

specifies the mode to use in accessing the file. If you omit the rac value, the 
default access mode is sequential file transfer by records. Sequential file 
transfer modes (3 and 5) cause any rac value in a subsequent GETNFW or 
PUTNFW calls to be ignored until you close the file. If the file is open for 
record access, the rac argument can be one of the following: 



Sequential by record 

1 Random by relative record number (RRN) 

2 Random by record file address (RFA) 

3 Sequential file transfer by records (default) 

If the file is open for block access, the rac argument can be one of the fol- 
lowing: 

4 Random blocks by virtual block number (VBN) 

5 Sequential file transfer by blocks 
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keyptr 

specifies the record. The length is assumed from the rac argument value. 
RAC Key 

1 Two- word binary value of RRN 
Low-order word first 

2 Three-word binary RFA 
Low-order word first 

4 Two-word binary value of VBN 

Low-order word first 

rop 

specifies record-processing options. Valid values are: 

1 Position to EOF 

4 Update if existing record 
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RENNFW 



RENNFW 

(Rename a File) 



3.9.17 RENNFW — Rename a File 
Use: 

Call RENNFW to rename a remote file. 

To return the new, fully-qualified file specification after the rename operation, 
use the set extended attributes (ATTNFW) call. Issue ATTNFW before issuing 
RENNFW, and use the name argument to specify a name buffer. On completion 
of the RENNFW call, the name buffer will contain the resulting file specification. 



Formats: 



FORTRAN : CALL RENNFW {lun ,status,node, ident, of He, nfile) 



COBOL: 



CALL "RENNFW" USING lun, status, node, ident, of He, nfile. 



BASIC: 



CALL RENNFW BY REF (lun%,status%( ),node$,ident$, 

ofile$,nfile%) 



Arguments: 



lun 



specifies the logical unit number of the logical link over which to rename a 
remote file. See the definition in Section 3. 9. 7. 



status 



specifies completion status information on return from RENNFW. See the 
definition for your language in Section 3. 9. 7. Refer to Table C-1 in Appen- 
dix C for a complete code list. 



node 



specifies the name of the node on which to rename the file. See the defini- 
tion in Section 3 9 7. 
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RENNFW 



ident 

is an array /string containing explicit access control information. See the defi- 
nition in Section 3 9 7. 

ofile 

specifies an ASCIZ array /string containing the current name of the file to 
rename. 

nfile 

specifies an ASCIZ array /string containing the new file specification for the 
file to rename. 
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SPLNFW, SUBNFW, OPWNFW 



SPLNFW, SUBNFW, OPWNFW 



3.9.18 SPLNFW — Create, Write, and Print a Fiie 

SUBNFW — Create, Write, and Execute a File 
OPWNFW — Create and Open a File for Writing Records 

Use: 

Call one of the following subroutines to create a file.- 

Call SPLNFW to create, write to, and print a new remote file at the remote 



node. 



Call SUBNFW 



to create, write to, and submit a new remote file to the re- 
mote batch/command file processor for execution. The file 
is deleted after execution. Successful completion of this call 
implies that the remote node handled the file properly, but 
not that the file ran or ran properly. 



Call OPWNFW 



to create and open a sequential file for writing records. 



Formats: 



FORTRAN: 



CALL 




{lun ,status, node, ident, if He, ichar, len , 
{iblock\) 



COBOL: 



CALL 




USING lun ,status,node, ident, if He, 
ichar, len , [iblock] . 



BASIC: 



CALL 




BY REF {lun%,status%{),node$,ident$, 
ifile$ , ichar$ , len % ,[iblock % ]) 
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SPLNFW, SUBNFW, OPWNFW 



Arguments: 

lun 

specifies the logical unit number of the logical link for the SPLNFW, 
SUBNFW, or OPWNFW call. Use the same LUN for any succeeding 
PUTNFW, PRGNFW, or CLSNFW call. See the definition in Section 3 9 7. 

* status 

specifies status completion information on return from SPLNFW, SUBNFW, 
or OPWNFW. See the definition for your language in Section 3 9 7. Refer to 
Table C-1 in Appendix C for a complete code list. 

node 

specifies the name of the node for the file to open using SPLNFW, SUBNFW 
or OPWNFW. See the definition in Section 3 9 7. 

ident 

is an array/string containing explicit access control information. See the defi- 
nition in Section 3 9 7. 

ifile 

specifies an ASCIZ string containing the file specification for the file to be 
opened using SPLNFW, SUBNFW, or OPWNFW. 

* ichar 

is a 3-element array/string. If the values you specify differ from those stored 
in the file, the stored values are used. When the open call completes, the 
ichar array /string contains the stored values. Check these values to see how 
the file was actually opened. Make sure you specify the appropriate ASCII 
letter code as defined in the following three fields: 

ichar{\)- Mode 

Letter Code Description 

A ASCII file 

I Binary image file 
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ichar{2) - Record Format 



Letter Code Description 

U Undefined format records 

F Fixed length records 

V Variable length records 

S Sequenced variable length records (VFC) 

A ASCII stream format 

ichar(^) - Carriage Control 

Letter Code Description 

F FORTRAN carriage control 

T Terminal carriage control 

N No carriage control 

P Print file VFC 



The ichar array /string specifies values for the new file. 
len 

is an integer variable that specifies record length. If record lengths vary, 
enter the maximum record length. A null value (0) implies there is no maxi- 
mum record length. 

iblock 

is an integer variable that specifies the number of blocks to allocate for file 
creation. Enter one of the following values: 



Entry Description 

Dynamic allocation 

+ n Number of noncontiguous blocks 

(where n = number of blocks) 

-n Number of contiguous blocks 

(where w = number of blocks) 



When SPLNFW, SUBNFW, or OPWNFW completes, iblock specifies the 
number of blocks allocated (if you specified a + w or a -w argument), or (if 
you specified dynamic allocation). 
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SPLNFW, SUBNFW, OPWNFW 

If the system cannot allocate the number of requested blocks, an error 
returns and frees the LUN. If you omit the iblock argument, the system allo- 
cates space dynamically. 
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3.9.19 FORTRAN Remote File Access Programming Examples 



The following programs illustrate FORTRAN remote file access. The first example 
appends a local file to a remote file. The second example reads the contents of one 
remote file into another. 

These examples are included in your tape or disk kit. 
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3.9.19.1 Append Example 

The FTNAPP program appends the contents of a local ASCII file to the end of a 
remote ASCII file and then closes both files. If an error occurs, the program dis- 
plays an error message. 

c 

C Copyright (C) 1983, 1985, 1986, 1987 by 

C Digital Equipment Corporation, Maynard, Mass. 

C 

c 

C This software is furnished under a license and may be used and copied 
C only in accordance with the terms of such license and with the 
C inclusion of the above copyright notice. This software or any other 
C copies thereof may not be provided or otherwise made available to any 
C other person. No title to and ownership of the software is hereby 
C transferred. 
C 

C The information in this software is subject to change without notice 
C and should not be construed as a commitment by Digital Equipment 
C Corporation. 
C 

C Digital assumes no responsibility for the us? or reliability of its 

C software on equipment which is not supplied by Digital. 

C 

C 

C FTNAPP. FTN — Append a local ASCII file to a remote ASCII file 
C 

C This program illustrates DECnet remote file access support for FORTflAN. 
C 

C To task build, use the following command string: 
C 

C FTNAPP , FTNAPP = FTNAPP 

C LB: [1,1]F4P0TS/LB 

C LB: [1,1]NETF0R/LB 

C LB: [1,1]NETF0R/LB:NFAFSR 

C LB: [1,1]RMSLIB/LB 

C / 

C UNITS=10 

C EXTSCT=$$FSR1:2700 

C ACTFIL=4 

C EXTTSK=1000 

C // 

c 

BYTE 
BYTE 
BYTE 
INTEGER 
INTEGER 
INTEGER 
LOGICAL 
COMMON 

C 

C Initialize LUNs for the network, input file, and output file 
C 

DATA NETLUN, INPLUN,OUTLUN 71,2,3/ 

C 

C ASCII files. Variable length records and FORTRAN carriage control 
C 

(continued on next page) 



(if RMS is included) 



(if RMS is included) 



UID(40) , PAS (40) ,ACC(40) ,N0D(7) 

INPFIL(65) ,OUTFIL(65) 

BUFFER(128) ,IDENT(120) ,ICHAR(3) 

NETLUN , INPLUN , OUTLUN , LNKNUM , MBXFLG 

U I DLEN , PASLEN , ACCLEN , NODLEN 

I NPLEN , OUTLEN , I STAT ( 2 ) , MSTAT ( 3 ) , I DENTL 

EOF 

I DENTL, I DENT 
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c 
c 
c 

10 



DATA ICHAR/'A' , 'V , 'FV 

Build a user ID string in the IDENT array 

IDENTL = 
TYPE 100 

ACCEPT 130,UIDLEN, {UID(I) , I=1,UIDLEN) 
CALL BLDID(UID,UIDLEN) 

Build a password string in the IDENT array 

TYPE 110 

ACCEPT 130,PASLEN, (PAS(I) , I=1,PASLEN) 
CALL BLDID(PAS,PASLEN) 



! Prompt for UID 

! Read in a string 

! Store UID into IDENT array 



! Prompt for PAS 

! Read in a string 

! Store PAS into IDENT array 



Build an account number string in the IDENT array 



TYPE 120 

ACCEPT 130,ACCLEN, (ACC(I) , I=1,ACCLEN) 
CALL BLDID(ACC, ACCLEN) 

Build a remote node name string 

TYPE 140 

ACCEPT 150,NODLEN, (NOD( I) , I = 1,N0DLEN) 
NOD(NODLEN+1) = 

Build a local input filename string 



! Prompt for ACC 

! Read in a string 

! Store ACC into IDENT array 



! Prompt for a node name 

! Read in a string 

! Terminate nodename string 



! Prompt for input filename 



TYPE 160 

ACCEPT 180,INPLEN, (INPFIL(I) , 1=1 , INPLEN) ! Read in a string 
INPFIL( INPLEN+1)=0 ! Terminate input file string 

Build a remote output filename string 

TYPE 170 ! Prompt for output filename 

ACCEPT 180 ,OUTLEN, (OUTFIL( I ) , 1=1 ,OUTLEN) ! Read in a string 
0UTFIL(0UTLEN+1 ) =0 ! Terminate output file string 

Open access to the network - only one link, use long connect block 



LNKNUM = 1 
MBXBLF = 1 
EOF = .FALSE, 



! Allow only one link 

! Set long connect block flag 

I Clear end-of-file flag 



CALL OPNNTW ( NETLUN , ISTAT ,MSTAT , LNKNUM, ,MBXFLG) 
IF (ISTAT(l) .EQ. 1) GOTO 10 

TYPE *, 'Cannot open network, status = ISTAT 
GOTO 90 

Open local input and remote output files 



Access the network 
If success, proceed 
Else, report error 
and finish 



OPEN (UNIT=INPLUN,NAME=INPFIL,TYPE='OLD' , READONLY, ERR=50) ! Open input 
CALL OPANFW (OUTLUN , ISTAT , NOD, IDENT , OUTFIL , ICHAR, LENGTH) ! Open output 
IF (ISTAT(I) .EQ. 1) GOTO 20 1 I f OK , proceed 
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c 
c 
c 

20 



c 
c 
c 

30 
40 



c 
c 
c 

50 

C 

C 

C 

60 

70 

80 

90 



C 
C 
C 

100 
110 
120 
130 
140 
150 
160 
170 
180 
190 



TYPE *, 'Cannot open output file, status = ISTAT ! Else, report er 
GOTO 70 ! and finish 

Main loop - read record from local file, write to remote file 

READ (INPLUN,190,END=30,ERR=40) ICNT3 , ( BUFFER( I ) , 1=1 , ICNT3 ) 



CALL PUTNFW ( OUTLUN , I STAT , I CNT3 , BUFFER ) 
IF (ISTAT(I) ,EQ. 1) GOTO 20 
TYPE *, 'Write error, status = ', ISTAT 
GOTO 60 



Put/write record to output 
If success, loop 
Else, report error 
and finish 



Last read is complete. Print error message if not end of file, 



EOF = .TRUE. 

IF (EOF) GOTO 60 

TYPE *,'Read error, status = ', ISTAT 
GOTO 60 

Process FORTRAN OPEN error 



Indicate normal completion 
No read error if end-of-fi 
Else, print error message 
and finish 



TYPE *, 'Cannot open local input file' ! Indicate that OPEN failed 
GOTO 80 ! and finish 

Finish - close files, deaccess the network, print status and exit 



CALL CLSNFW (OUTLUN, ISTAT) 
CLOSE (UNIT=INPLUN) 
CALL CLSNTW (ISTAT) 
IF (EOF) TYPE *, 'Successful completion' 

IF (.NOT. EOF) TYPE *, 'Error completion' 
STOP 

Formats 

FORMAT ('$User ID (39 char, max.): ') 
FORMAT ('$Password (39 char, max.): ') 
FORMAT ('$Account (39 char, max.): ') 
FORMAT (Q,39A1) 

FORMAT (•$Node (6 char, max.): ') 
FORMAT (Q,6A1) 

FORMAT ('$Input file (64 char, max.): ') 
FORMAT ('$Output file (64 char, max.): ') 
FORMAT (Q,64A1) 
FORMAT (Q,128A1) 



Close remote output file 
Close local input file 
Deaccess the network 



END 

BLDID (fld,fldlen) - Build an ASCIZ IDENT field 



SUBROUTINE 
BYTE 
INTEGER 
COMMON 

DO 10, 1=1, LEN 



BLDID (FLD,LEN) 
IDENT( 30) ,FLD(80: 
IDENTL,LEN 
IDENTL, IDENT 



(continued on next page) 
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IDENT( IDENTL+,I ) = FLD(l) 
10 CONTINUE 

IDENTL = IDENTL+I 
IDENT(IDENTL) = 
RETURN 

END 
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3.9.19.2 Read/Write Example 



The FTNRRW program reads the contents of one remote file into another remote 
file. When the program encounters an end-of-file character, the last record is 
written to the remote file and both files are closed. If a read or write error occurs, 
the program displays a message and exits. 

c 

C Copyright (C) 1983, 1985, 1986, 1987 by 

C Digital Equipment Corporation, Maynard, Mass. 

C 

C 

C This software is furnished under a license and may be used and copied 
C only in accordance with the terms of such license and with the 
C inclusion of the above copyright notice. This software or any other 
C copies thereof may not be provided or otherwise made available to any 
C other person. No title to and ownership of the software is hereby 
C transferred. 
C 

C The information in this software is subject to change without notice 
C and should not be construed as a commitment by Digital Equipment 
C Corporation. 
C 

C Digital assumes no responsibility for the use or reliability of its 

C software on equipment which is not supplied by Digital. 

C 



FTNRRW. FTN - Read records from one remote file, write to another 

This program illustrates DECnet remote file access support for FORTRAN. 

To task build, use the following command string: 

FTNRRW, FTNRRW = FTNRRW 
LB: [1,1]F4P0TS/LB 
LB: [1,1]NETF0R/LB 
LB : [ 1 , 1 ] NETFOR/LB : NFAFSR 
LB: [1, 1]RMSLIB/LB 
/ 

UNITS=10 

EXTSCT=$$FSR1 : 10000 
ACTFIL=4 
EXTTSK=1000 
// 



(if RMS is included) 



(if RMS is included) 



Remote input file: RN0DE1"NFAR PRIV 123" : rFTNRRW. INP 
Remote output file: RN0DE2"NFAR PRIV 123" : :FTNRRW.OUT 



INTEGER 

INTEGER 

INTEGER 

BYTE 

LOGICAL 



NETLUN, INPLUN,OUTLUN 
MBXFLG , LNKNUM 
ISTAT(2) ,RECLEN 

IDINF0(14) , ICHARS(3) ,RECBUF(512) 
EOF 



Specify LUNs for the network, input file, and output file 
DATA NETLUN, I NPLUN,OUTLUN 77,1,2/ 

Specify ASCIZ IDENT strings: user, password and account 

(continued on next page) 
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DATA IDINFO/'N' ,'F','A','R',0,'P','R','I','V',0,'1','2','3',0/ 

C 

C Image mode. Variable length records and Terminal carriage control 
C 

DATA ICHARS / ' I ' , ' V , ' T ' / 

C 

C Initialize some flags 
C 

MBXFLG = 1 ! Set long connect block flag 

LNKNUM = 2 ! Set number of links 

EOF = .FALSE. ! Initialize end-of-file flag 

C 

C Open access to the network - allow two links, use long connect block 
C 

CALL OPNNTW ( NETLUN , I STAT , , LNKNUM , , MBXFLG ) 
IF (ISTAT(I) .EQ. 1) GOTO 10 

TYPE *, 'Cannot access network, status = ISTAT 
GOTO 80 

C 

C Open remote input file 
C 

10 CALL OP RNFWdNPLUN, ISTAT, 'RNODEl' , IDINFO, 

1 * [NFAR]FTNRRW. INP' , 

1 ICHARS,RECLEN) 
IF (ISTAT(I) .EQ. 1) GOTO 20 

TYPE *, 'Cannot open remote input file', ISTAT 
GOTO 70 

C 

C Open remote output file 
C 

20 CALL OPWNFW{OUTLUN, ISTAT, •RN0DE2' , IDINFO, 

1 ' [ NEAR ] FTNRRW . OUT ' , 

1 ICHARS, RECLEN) 

IF ( ISTAT (1) .EQ. 1) GOTO 30 

TYPE *, 'Cannot open remote output file', ISTAT 
GOTO 60 

C 

C Main loop - transfer records until end-of-file 
C 

C Get a record from the input fi.le. 
C 

30 CALL GETNFW( INPLUN, ISTAT, 512 ,RECBUF) 

IF (iSTATd) .NE. 1) GOTO 40 ! If read error, check for EOF 
RECLEN = ISTAT(2) ! Set number of bytes to write 

C 

C Put the record to the output file 
C 

CALL PUTNFW ( OUTLUN , I STAT , RECLEN , RECBUF ) 

IF (ISTAT(l) .EQ. 1) GOTO 30 ! If write succeeded, loop 
TYPE *, 'Write error, status = ', ISTAT 
GOTO 50 

C 

C The last read failed. Print error message if not an end-of-file. 
C 

40 IF (ISTAT(2) .EQ. '050047'O) EOF = .TRUE. 

IF (.NOT. EOF) TYPE *,'Read error, status = ', ISTAT 

C 

C Finish - close files, deaccess network, print status and exit 
C 

50 CALL CLSNFW( OUTLUN, ISTAT) ! Close output file 

60 CALL CLSNFW( INPLUN, ISTAT) • Close input file 

70 CALL CLSNTW( NETLUN) ! Deaccess the network 

80 IF (EOF) TYPE *, 'Successful completion' 

IF (.NOT. EOF) TYPE *, 'Execution failure' 

STOP 

END 



3-130 



DECnet-RSX Programmer's Reference Manual 



3.9.20 COBOL Remote File Access Programming Examples 

The following programs illustrate COBOL remote file access. They are included 
in your tape or disk kit. 
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3.9.20.1 Append Example 



The program COBAPP appends the contents of a local ASCII file to the end of a 
remote ASCII file and then closes both files. If an error occurs, the program dis- 
plays an error message. 

* 

* Copyright (C) 1983, 1985, 1986, 1987 by 

* Digital Equipment Corporation, Maynard, Mass. 
* 

* 

* This software is furnished under a license and may be used and copied 

* only in accordance with the terms of such license and with the 

* inclusion of the above copyright notice. This software or any other 

* copies thereof may not be provided or otherwise made available to any 

* other person. No title to and ownership of the software is hereby 

* transferred. 
* 

* The information in this software is subject to change without notice 

* and should not be construed as a commitment by Digital Equipment 

* Corporation. 
* 

* Digital assumes no responsibility for the use or reliability of its 

* software on equipment which is not supplied by Digital. 
* 



IDENTIFICATION DIVISION. 
PROGRAM- ID. COBAPP. 

**************************************************** 
* 

* This program appends the contents of a local ASCII file 

* to a remote ASCII file and then closes both files. 
* 

* To task build, use the following command string: 
* 

* COBAPP, COBAPP =- 

* COBAPP, [ 1, 1 ]NETF0R/LB,C81LIB/LB,RMSLIB/LB,NETF0R/LB:NFAFSR 

* / 

* UNITS=10 

* EXTSCT=$$FSR1 : 2700 

* ACTFIL=4 

* EXTTSK=1000 (if RMS is included) 

* // 
* 

*************************************************************** 



ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER. PDP-11. 
OBJECT-COMPUTER. PDP-11. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 

SELECT LOCAL-FILE ASSIGN TO "DBG:". 
DATA DIVISION. 
FILE SECTION. 



FD LOCAL-FILE 

LABEL RECORDS ARE STANDARD 
VALUE OF ID IS LOCAL. 
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01 LOCAL-REC 



PIC X(80) . 



WORKING -STORAGE SECTION. 
1 MSGS . 



03 


MSGl . 












05 FILLER 


PIC X( 36 ) 


VALUE " 


MAIL BOX CREAT 






" I ON ERROR , 


lOST(l) = 


n 






05 MSGl-STATl 


PIC -99999. 










05 FILLER 


PIC X( 11 ) 


VALUE " 


I0ST(2) 


_ II 




05 MSG1-STAT2 


PIC -99999. 








03 


MSG2 . 












05 FILLER 


PIC X( 38 ) 


VALUE " 


CAN NOT 


OPEN R 






"EMOTE FILE 


, lOST(l) 


_ If 






05 MSG2-STAT1 


PIC -99999. 










05 FILLER 


PIC X(ll) 


VALUE " 


I0ST(2) 


_ It 




05 MSG2-STAT2 


PIC -99999. 








03 


MSG3 . 












05 FILLER 


PIC X(42) 


VALUE " 


WRITE ERROR FR 






"OM REMOTE 


FILE. lOST(l) = 






05 MSG3-STAT1 


PIC -99999. 










05 FILLER 


PIC X(ll) 


VALUE " 


I0ST(2) 


_ n 




05 MSG3-STAT2 


PIC -99999. 








03 


MSG4. 












05 FILLER 


PIC X{39) 


VALUE " 


CAN NOT 


CLOSE 






"REMOTE FILE. lOST(l) 


_ II 






05 MSG4-STAT1 


PIC -99999. 










05 .FILLER 


PIC X(ll) 


VALUE " 


I0ST(2) 






05 MSG4-STAT2 


PIC -99999. 








03 


MSG5. 












05 FILLER 


PIC X(35) 


VALUE " 


CAN NOT 


CLOSE 






"NETWORK. 


lOST(l) = " 








05 MSG5-STAT1 


PIC -99999. 










05 FILLER 


PIC X(ll) 


VALUE " 


I0ST(2) 






05 MSG5-STAT2 


PIC -99999. 









01 ARRAYS. 

03 lOST. 

05 lOSTAT OCCURS 2 TIMES PIC S9999 USAGE COMP . 
03 MSTAT. 

05 MSTATS OCCURS 3 TIMES PIC S9S99 USAGE COMP. 
01 STORE-STUFF. 



03 


LOCAL 


PIC 


X(26) . 






03 


I DENT 


PIC 


X(30) . 






03 


USERID 


PIC 


X(12) . 






03 


PASSWD 


PIC 


X(6) . 






03 


ACCNT 


PIC 


X(9) . 






03 


REMOTE- FILE 


PIC 


X(30) . 






03 


FILLER 


PIC 


X. 






03 


OPNLUN 


PIC 


9 


COMP VALUE 


4 . 


03 


COUNT 1 


PIC 


9 


COMP VALUE 


1 . 


03 


APPLUN 


PIC 


9 


COMP VALUE 


3. 


03 


LENGTH 1 


PIC 


S9999 


USAGE COMP. 




03 


BLOCKl 


PIC 


S9999 


USAGE COMP. 




03 


REC-LENGTH 


PIC 


S99 


COMP VALUE 


80 


03 


NODE-NAME 


PIC 


X(7) . 






03 


TEMP-NODE 


PIC 


X(6) . 






03 


TEMP- REMOTE 


PIC 


X(29) . 






03 


I CHAR 


PIC 


X(3) 


VALUE "AVF" 





(continued on next page) 
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01 NULLl PIC 9 COMP VALUE 0. 

01 NULLS REDEFINES NULLl. 

03 NUL OCCURS 2 TIMES PIC X(l). 
PROCEDURE DIVISION. 



* * 

* Get accountinq information for remote node from * 

* terminal and form ASCIZ string with this information * 

* for OPRNFW and OPWNFW. * 

* * 
**************************************************^ 

Al 00 -START. 

DISPLAY " INPUT USER ID: ". 
ACCEPT USERID. 
DISPLAY " INPUT PASSWORD: 
ACCEPT PASSWD. 

DISPLAY " INPUT ACCOUNT NUMBER: *• . 
ACCEPT ACCNT. 
STRING USERID 

NUL(l) 

PASSWD 

NUL ( 1 ) 

ACCNT 

NUL(l) DELIMITED BY SIZE 
INTO I DENT. 

************************************************** 

* * 

* Get. remote node name and form ASCIZ string. * 

* * 
***************************************************************** 

DISPLAY " INPUT REMOTE NODE NAME: ". 
ACCEPT TEMP-NODE. 
STRING TEMP-NODE 

NUL(l) DELIMITED BY SIZE 

INTO NODE-NAME. 

***************************************************************** 

* * 

* Get remote file name and form ASCIZ string. * 

* * 
***************************************************************** 

DISPLAY " ENTER FILE SPEC. OF REMOTE FILE FOR APPEND". 
ACCEPT TEMP-REMOTE. 
STRING TEMP-REMOTE 

NUL(l) DELIMITED BY SIZE 

INTO REMOTE- FILE. 
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***************************************************** 

* * 

* Get local file name. * 

* * 

***************************************************************** 

DISPLAY " ENTER FILE SPEC. OF LOCAL FILE TO BE APPENDED". 
ACCEPT LOCAL. 

***************************************************************** 

* * 

* Access the network. If the call completes * 

* unsuccessfully, write an error message and exit. * 

* ^ 

************************************************^**^^^^^^^yt^^^^^^^ 

CALL "OPNNTW" USING 

OPNLUN 
lOST 
MSTAT 
COUNT 1. 
IF lOSTAT (1) = 1 

NEXT SENTENCE 

ELSE 

MOVE lOSTAT (1) TO MSGl-STATl 
MOVE lOSTAT (2) TO MSG1-STAT2 
DISPLAY MSGl 
GO ElOO-END. 

***************************************************************** 

* * 

* Open the local file. Open the remote file for * 

* append. If unable to open the remote file, write * 

* an error message and deaccess the network. * 

* * 
***************************************************************** 

OPEN INPUT LOCAL- FILE. 
CALL "OPANFW" USING 

APPLUN 

lOST 

NODE-NAME 
I DENT 

REMOTE-FILE 
I CHAR 
LENGTHl 
BLOCKl. 
IF lOSTAT (1) = 1 

NEXT SENTENCE 

ELSE 

MOVE lOSTAT (1) TO MSG2-STAT1 
MOVE lOSTAT (2) TO MSG2-STAT2 
DISPLAY MSG2 
GO DIOO-CLOSE. 
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********************************************************* 

* * 

* Read a record from the local file and append it to * 

* the remote file until the end-of-file is encountered * 

* in the local file. If an error occurs while writing * 

* to the remote file, print an error message and exit. * 

* * 
***************************************************************** 



BIOO-READ. 

MOVE SPACES TO LOCAL-REC. 
READ LOCAL- FILE RECORD 

AT END GO CIO -EOF. 
CALL "PUTNFW" USING 

APPLUN 

lOST 

REC- LENGTH 

LOCAL-REC. 
IF lOSTAT (1) = 1 GO BIOO-READ. 
MOVE lOSTAT (1) TO MSG3-STAT1. 
MOVE lOSTAT (2) TO MSG 3 -ST AT 2. 
DISPLAY MSGS. 
GO ElOO-END. 



***************************************************************** 

* * 

* When the end-of-file is encountered in the local * 

* file, close the local and remote files. If unable * 

* to close the remote file, print an error message * 

* and exit. * 

* * 
***************************************************************** 

ClOO-EOF. 

CLOSE LOCAL-FILE. 
CALL "CLSNFW" USING 

APPLUN 

lOST. 
IF lOSTAT (1) = 1 

NEXT SENTENCE 

ELSE 

MOVE lOSTAT (1) TO MSG4-STAT1 
MOVE lOSTAT (2) TO MSG4-STAT2 
DISPLAY MSG4 
GO ElOO-END. 
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************************************************* 

* * 

* Deaccess the network. Display an error message * 

* if the call does not complete successfully. * 

* * 
***************************************************************** 



Dl 00 -CLOSE. 

CALL "CLSNTW"' USING 

lOST. 
IF lOSTAT (1) = 1 

NEXT SENTENCE 

ELSE 

MOVE lOSTAT (1) TO MSG5-STAT1 
MOVE lOSTAT (2) TO MSG5-STAT2 
DISPLAY MSGS 
GO ElOO-END. 

DISPLAY "APPEND COMPLETE. END COBAPP PROGRAM EXECUTION". 
ElOO-END. 

STOP RUN. 
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3.9.20.2 Read/Write Example 



The program COBRRW reads the contents of one remote file into another remote 
file. When an end-of-file character is encountered, the last record is written to the 
remote file and both files are closed. 

* 

* Copyright (C) 1983, 1985, 1986, 1987 by 

* Digital Equipment Corporation, Maynard, Mass. 
* 

* 

* This software is furnished under a license and may be used and copied 

* only in accordance with the terms of such license and with the 

* inclusion of the above copyright notice. This software or any other 

* copies thereof may not be provided or otherwise made available to any 

* other person. No title to and ownership of the software is hereby 

* transferred. 
* 

* The information in this software is subject to change without notice 

* and should not be construed as a commitment by Digital Equipment 

* Corporation. 
* 

* Digital assumes no responsibility for the use or reliability of its 

* software on equipment which is not supplied by Digital. 
* 



IDENTIFICATION DIVISION. 
PROGRAM-ID. COBRRW. 

********************************************************* 
* 

* This program reads the contents of a remote file into 

* another remote file. The program reads and writes records 

* until it encounters an end-of-file, at which time it writes 

* the last record to the remote file and closes both files. 
* 

* To task build, use the following command string: 
* 

* COBRRW, COBRRW =- 

* COBRRW ,[1,1] NETFOR/LB , C8 1 L I B/LB , RMSL I B/LB , NETFOR/LB : NFAFSR 

* / 

* UNITS=10 

* EXTSCT=$$FSR1: 10000 

* ACTFIL=4 

* EXTTSK=1000 (if RMS is included) 

* // 
* 

****************************************************************** 

ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER. PDP-11. 
OBJECT-COMPUTER. PDP-11. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 

SELECT DUMMY-FILE ASSIGN TO "COBRRW . DUM" . 

DATA DIVISION. 



* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
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FILE SECTION. 

FD DUMMY-FILE 

LABEL RECORD STANDARD. 
01 DUMMY-FILE-REC. 

02 FILLER PIC X(132) 

WORKING- STORAGE SECTION. 
01 MSGS. 

3 MSGl. 

05 FILLER 



01 



01 



03 



03 



03 



03 



05 MSGl-STATl 
05 FILLER 
05 MSG1-STAT2 
MSG2 . 

05 FILLER 

05 MSG2-STAT1 
05 FILLER 
05 MSG2-STAT2 
MSG3 . 

05 FILLER 

05 MSG3-STAT1 
05 FILLER 
05 MSG3-STAT2 
MSG4 . 

05 FILLER 



MSG4-STAT1 
FILLER 
MSG4-STAT2 



05 
05 
05 
MSGS. 

05 FILLER 



MSG5-STAT1 

FILLER 

MSG5-STAT2 



05 

05 

05 
ARRAYS . 
03 lOST. 

05 lOSTAT OCCURS 
03 MSTAT. 

05 MSTATS OCCURS 
STORE-STUFF. 



PIC X(34). 
"ETWORK. 
PIC -99999 
PIC X(ll) 
PIC -99999 



PIC X(44) 
"EMOTE INPUT 
PIC -99999. 
PIC X(ll) 
PIC -99999. 

PIC X(45) 
"EMOTE INPUT 
PIC -99999. 
PIC X(ll) 
PIC -99999. 

PIC X(24) 
"OST(l) = ". 
PIC -99999. 
PIC X(ll) 
PIC -99999. 

PIC X(25) 
"lOST(l) = 
PIC -99999. 
PIC X(ll) 
PIC -99999. 



VALUE 
lOST(l) = 



CAN NOT OPEN N 



VALUE " I0ST(2) = 



VALUE 
FILE. 



" CAN NOT OPEN R 
lOST(l) = ". 



VALUE " I0ST(2) 



VALUE 
FILE. 



" CAN NOT 
lOST(l) = 



OPEN R 



VALUE " I0ST(2) = 



VALUE " READ ERROR. 



VALUE " I0ST(2: 



VALUE 



WRITE ERROR, 



VALUE " I0ST(2) = 



2 TIMES PIC S9999 USAGE COMP. 

3 TIMES PIC S9999 USAGE COMP. 



03 


OPNLUN 


PIC 


9 


COMP VALUE 2. 


03 


COUNT 1 


PIC 


9 


COMP VALUE 2. 


03 


LENGTHl 


PIC 


S9999 


USAGE COMP. 


03 


BLOCKl 


PIC 


S9999 


USAGE COMP. 


03 


INPLUN 


PIC 


9 


COMP VALUE 3. 


03 


OUTLUN 


PIC 


9 


COMP VALUE 4. 


03 


I 


PIC 


999 


USAGE COMP. 


03 


I ARRAY-SIZE 


PIC 


99 


COMP VALUE 80. 


03 


EOF 


PIC 


99999 


COMP VALUE 20 519 


03 


EOFFG 


PIC 


S 


USAGE COMP. 


03 


TTRUE 


PIC 


S 


COMP VALUE -1. 


03 


FFALSE 


PIC 


S 


COMP VALUE 0. 
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03 


I DENT 


03 


USERID 


03 


PASSWD 


03 


ACCNT 


03 


TEMP-NODE 


03 


NODE-NAME 


03 


TEMP- INPUT 


03 


REMOTE- INPUT 


03 


TEMP-OUTPUT 


03 


REMOTE-OUTPUT 


03 


I CHAR 


03 


I ARRAY 



01 NULLl 

01 NULLS REDEFINES NULLl. 

03 NUL OCCURS 2 TIMES 
PROCEDURE DIVISION. 



PIC X(30) 
PIC X(12) 
PIC X{6) . 
PIC X(9) . 
PIC X(6) . 
PIC X(7) . 
PIC X(29) 
PIC X(30) 
PIC X(29) 
PIC X(30) 
PIC X(3) 
PIC X(80) 
PIC 9 

PIC X(l) . 



VALUE "AVF". 
COMP VALUE 



**************************************************** 

* * 

* Get. account ing information for remote node and * 

* form ASCIZ string for DECnet remote file access * 

* subroutines. * 

* * 
***************************************************************** 

AlOO-START. 

DISPLAY "INPUT USER ID:". 
ACCEPT USERID. 
DISPLAY " INPUT PASSWORD:". 
ACCEPT PASSWD. 

DISPLAY " INPUT ACCOUNT NUMBER:". 
ACCEPT ACCNT. 
STRING USERID 

NUL( 1) 

PASSWD 

NUL(l) 

ACCNT 

NUL(l) DELIMITED BY SIZE 
INTO I DENT. 

***************************************************************** 

* * 

* Get remote node name and form ASCIZ string. * 

* * 
***************************************************************** 

DISPLAY " ENTER REMOTE NODE NAME:". 
ACCEPT TEMP-NODE. 
STRING TEMP-NODE 

NUL(l) DELIMITED BY SIZE 

INTO NODE -NAME. 

***************************************************************** 

* * 

* Get remote input and output file names and form * 

* ASCIZ string for each file. * 



***************************************************************** 
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DISPLAY " INPUT FILE SPEC. FOR INPUT FILE:". 
ACCEPT TEMP- INPUT, 
STRING TEMP- INPUT 

NUL(l) DELIMITED BY SIZE 

INTO REMOTE- INPUT. 
DISPLAY " INPUT FILE SPEC. FOR OUTPUT FILE:". 
ACCEPT TEMP-OUTPUT. 
STRING TEMP-OUTPUT 

NUL(l) DELIMITED BY SIZE 

INTO REMOTE-OUTPUT. 



************************************************ 

* * 

* Access the network. If the call does not complete * 

* successfully, display an error message and exit. * 

* ♦ * 
***************************************************************** 



CALL "OPNNTW" USING 

OPNLUN 

lOST 

MSTAT 

COUNT 1. 
IF lOSTAT (1) = 1 

NEXT SENTENCE 

ELSE 

MOVE lOSTAT (1) TO MSGl-STATl 
MOVE lOSTAT (2) TO MSG1-STAT2 
DISPLAY MSGl 
GO ElOO-END. 

***************************************************************** 

* * 

* Open remote file for input. If there is an open * 

* error, print an error message and exit. * 

* * 
***************************************************************** 



CALL "OPRNFW" USING 
INPLUN 
lOST 

NODE-NAME 
I DENT 

REMOTE- INPUT 
I CHAR 
LENGTH 1 
BLOCKl . 
IF lOSTAT (1) =1 

NEXT SENTENCE 

ELSE 

MOVE lOSTAT (1) TO MSG2-STAT1 

(continued on next page) 



FORTRAN, COBOL, and BASIC-PLUS-2 Programming Facilities 



3-141 



MOVE lOSTAT (2) TO MSG2-STAT2 
DISPLAY MSG2 
GO ElOO-END. 



************************************************************ 

* * 

* Open remote file for output. If there is an open * 

* error, display an error message and exit. * 

* * 
***************************************************************** 



CALL "OPWNFW" USING 
OUTLUN 
lOST 

NODE-NAME 
I DENT 

REMOTE-OUTPUT 
I CHAR 
I CHAR 
LENGTH 1 
BLOCK 1. 
IF lOSTAT (1) =1 

NEXT SENTENCE 

ELSE 

MOVE lOSTAT (1) TO MSG3-STAT1 
MOVE lOSTAT (2) TO MSG3-STAT2 
DISPLAY MSG3 
GO DIOO-CLOSE. 

***************************************************************** 

* * 

* Transfer records between the remote files. When * 

* the end-of-file is encountered, exit from the loop. * 

* Exit from the loop if a read or write error occurs * 

* and branch to the appropriate routine to display an * 

* error message. * 

* * 
***************************************************************** 



PERFORM LOOP VARYING I FROM 1 BY 1 UNTIL I = 100. 

LOOP. 

CALL "GETNFW" USING 
INPLUN 
lOST 

I ARRAY-SIZE 
I ARRAY. 

IF lOSTAT (1) NOT = 1 AND lOSTAT (2) NOT = EOF 

GO BIOO-READERR. 
MOVE lOSTAT (2) TO LENGTHl . 

IF lOSTAT (1) NOT = 1 AND lOSTAT (2) = EOF 
MOVE TTRUE TO EOFFG 

ELSE 

MOVE FFALSE TO EOFFG. 
IF EOFFG = TTRUE GO DIOO-CLOSE. 
CALL "PUTNFW" USING 
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OUTLUN 
lOST 
LENGTHl 
I ARRAY 

IF lOSTAT (1) NOT = 1 AND lOSTAT (2) NOT = EOF 
GO ClOO-WRITERR. 

********************************************** 

* * 

* A read error occurred during file transfer. Print * 

* an error message and exit. * 

* * 
***************************************************************** 

BIOO-READERR. 

MOVE lOSTAT (1) TO MSG4-STAT1. 
MOVE lOSTAT (2) TO MSG4-STAT2. 
DISPLAY MSG4. 
GO DIOO-CLOSE. 

***************************************************************** 

* * 

* A write error occurred during file transfer. Print * 

* an error message and exit. * 

* * 
***************************************************************** 

ClOO-WRITERR. 

MOVE lOSTAT (1) TO MSG5-STAT1. 
MOVE lOSTAT (2) TO MSG5-STAT2. 
DISPLAY MSGS. 

***************************************************************** 

* * 

* Close both remote files. * 

* * 
***************************************************************** 

DIOO-CLOSE. 

PERFORM LOOPl VARYING I FROM INPLUN BY 1 UNTIL I = OUTLUN. 

LOOPl. 

CALL "CLSNFW" USING 
I 

lOST. 

***************************************************************** 

* * 

* If an error occurred before encountering the * 

* end-of-file, exit. Otherwise the transfer was * 

* successful, so display a success message and * 

* exit. * 

* * 
***************************************************************** 

END-LOOPl. 

IF EOFFG NOT = TTRUE 
GO ElOO-END 

ELSE 

DISPLAY "END OF FILE REACHED. FILES CLOSED.". 

ElOO-END. 

STOP RUN. 

(continued on next page) 
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3.9.21 BASIC-PLUS-2 Remote File Access Programming Examples 



The following programs illustrate BASIC-PLUS-2 remote file access. The first 
example appends a local file to a remote file. The second example reads the con- 
tents of one remote file into another. 

These programs are included in your tape or disk kit. 
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3.9.21.1 Append Example 



The BASAPP program appends the contents of a local ASCII file to the end of a 
remote ASCII file and then closes both files. If an error occurs, the program dis- 
plays an error message. In the following example, the user ID, the password, and 
the account number are entered from the terminal. 

Copyright (C) 1983, 1985, 1986, 1987 by 
Digital Equipment Corporation, Maynard, Mass. 



This software is furnished under a license and may be used and copied 
only in accordance with the terms of such license and with the 
inclusion of the above copyright notice. This software or any other 
copies thereof may not be provided or otherwise made available to any 
other person. No title to and ownership of the software is hereby 
transferred. 

The information in this software is subject to change without notice 
and should not be construed as a commitment by Digital Equipment 
Corporat ion. 

Digital assumes no responsibility for the use or reliability of its 
software ©n equipment which is not supplied by Digital. 



10 



BASAPP. B2S - Append local file to remote file 

To task build, edit the task build command file 
file and the ODL file created by the build. 

1) Add the lines 

ACTFIL=4 

EXTSCT=$$FSR1 : 2700 
to the task build command file. 

2 ) Append 

-NETLIB-NETLB2 
to the USER: line of the ODL file. 

3) Add the lines 

NETLIB: .FCTR LB: [1,1]NETF0R/LB 
NETLB2: .FCTR LB : [ 1 , 1 ]NETFOR/LB : NFAFSR 
to the ODL file. 



ON ERROR GO TO 200 



! Error handler 



20 
\ 
\ 
\ 

30 

\ 
\ 
\ 



! ! ! Define array constants ! ! ! 

DIM ISTAT%(1%) ,JSTAT%(1%) ,KSTAT%(1%) ,LSTAT%(1%) ,MSTAT%(2%) 
DIM NSTAT%(1%) ! Define array elements 

NULL? = STRING$(1%,0%) ! Define null char for ASCIZ 



!!! Define constants !!! 
0PNLUN% = 2% 
MBXFLG% = 1% 
APPLUN% = 1% 
COUNT % =1% 



Network open LUN 

Long connect block flag 

File LUN 

Max # of logical links 
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\ FLAG% = 0% ! End of file flag & 
\ ICHAR$ = "AVF" ! Mode, type, carriage control 

40 INPUT "Remote node name (6 char. max. ) " ;NODNAM$ & 

\ IF LEN{N0DNAM$)>6% THEN PRINT & 

"Node name too long, please re-enter" & 
\ PRINT \ GO TO 40 

50 NODNAM$ = NODNAM$+NULL$ ! Create ASCIZ string for OPANFW 

60 INPUT "Remote output file (64 char. max. ) " ;OFIL$ & 

\ IF LEN(OFIL$)>64% THEN PRINT & 

"Remote output filename too long, please re-enter" & 
\ PRINT \ GOTO 60 

70 OFIL$ = OFIL$+NULL$ ! Create ASCIZ string for OPANFW 

80 INPUT "Local input file (64 char. max)";IFIL$ & 

\ IF LEN( IFIL$)>64% THEN PRINT S. 

"Local input filename too long, please re-enter" & 
\ PRINT \ GOTO 80 

90 INPUT "User ID (39 char. max.)";UID$ ! Get user ID & 

\ IF LEN(UID$)>39% THEN PRINT & 

"User ID too long, please re-enter" & 
\ PRINT \ GOTO 90 

100 INPUT "Password (39 char. max.)";PAS$ ! Get password & 

\ IF LEN(PAS$ )>39% THEN PRINT & 

"Password too long, please re-enter" & 
\ PRINT \ GOTO 100 

110 INPUT "Account (39 char. max.)";ACC$ ! Get account number & 

\ IF LEN(ACC$)>39% THEN PRINT & 

"Account number too long, please re-enter" & 
\ PRINT \ GOTO 110 

120 !!! Create ASCIZ string for IDENT in OPANFW !!! & 
\ IDENT$ = UID$+NULL$+PAS$+NULL$+ACC$+NULL$ 

130 !!! Open access to network - 1 link, long connect block !!! & 

\ CALL OPNNTW BY REF ( OPNLUN% , LSTAT% ( ) , MSTAT% ( ) , COUNT% & 

,,MBXFLG%) & 
\ IF LSTAT%(0%)=1% THEN 140 ! If OPNNTW succeeded, proceed 

ELSE PRINT "Cannot access network" ! Else, print message & 

\ PRINT "Status = ";LSTAT%(0%);",";LSTAT%(1%) & 
\ GO TO 220 ! status and exit 

140 !!! Open local file !!1 & 
\ OPEN IFIL$ FOR INPUT AS FILE #4 

150 !!! Open remote file for append !!! & 

\ CALL OPANFW BY REF ( APPLUN% , ISTAT% ( ) , NODNAM$ , IDENT$ , OFI L$ , & 

ICHAR$ ,LENGTH%, IBLOCK%) & 

\ IF ISTAT%(0%)=1% THEN 160 ! If successful, proceed & 

ELSE PRINT "Cannot open remote file." ! Else, print message, & 

\ PRINT "STATUS = "; ISTAT% ( 0% );","; ISTAT% ( 1% ) ! status & 
\ GO TO 180 ! and exit 
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160 !!! Read records from local file and write them to ! ! ! & 

\ ! ! ! remote file. ! ! ! & 

\ FLAG% = 1% ! Set flag for eof check & 

\ INPUT #4,TEMP$ ! Read from local file r 

\ CALL PUTNFW BY REF ( APPLUN% , JSTAT% ( ) , LEN( TEMP$ ) , TEMP$ ) & 

! Append to remote file & 

\ IF JSTAT%{0%)=1% THEN 160 ! If successful, loop & 

ELSE PRINT "Write error from remote file." ! Else, print msg, & 

\ PRINT "Status = ", •JSTAT%(0% );","; JSTAT% ( 1% ) ! status & 
\ GO TO 220 ! and exit 

170 !!! EOF found — close both files and network !!! & 

\ FLAG% = 0% ! Clear end of file flag & 

\ CLOSE #4 ! Close local file & 

\ CALL CLSNF-J BY REF(APPLUN% ,KSTAT% ( ) ) ! Close remote file & 

\ IF KSTAT%{0%)=1% THEN 180 ! If success, deaccess network & 

ELSE PRINT " Cannot close remote file." ! If close error, & 

\ PRINT "Status = " ;KSTAT%(0%) ; " , " ;KSTAT%(1%) & 
\ GO TO 220 ! Print message, status and exit 

180 CALL CLSNT BY REF (NSTAT% ( ) ) ! Deaccess network & 

\ IF NSTAT%(0%)=1% THEN 190 ! If success, append complete & 

ELSE PRINT "Cannot close network." ! If error, print & 

\ PRINT "Status = ";NSTAT%(0%) ;",";NSTAT$(1%) & 
\ GO TO 220 ! message, status and exit 

190 PRINT "Append complete. End program execution" & 
\ GO TO 220 

200 IF ERR <> 11 THEN 210 ! If not EOF, print error & 

ELSE IF FLAG%=0% THEN 210 ! If EOF and EOF flag not set, & 

! print error & 
ELSE RESUME 170 ! EOF so close both files 

210 PRINT "Error ";ERR;" at line ";ERL ! Print error and line number 

220 END 
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3.9.21 .2 Read/Write Example 



The BASRRW program reads the contents of one remote file into another remote 
file. When the program encounters an end-of-file character, the last record is 
written to the remote file and both files are closed. 

Copyright (C) 1983, 1985, 1986, 1987 by 
Digital Equipment Corporation, Maynard, Mass. 



This software is furnished under a license and may be used and copied 
only in accordance with the terms of such license and with the 
inclusion of the above copyright notice. This software or any other 
copies thereof may not be provided or otherwise made available to any 
other person. No title to and ownership of the software is hereby 
transferred. 

The information in this software is subject to change without notice 
and should not be construed as a commitment by Digital Equipment 
Corporation. 

Digital assumes no responsibility for the use or reliability of its 
software on equipment which is not supplied by Digital. 



10 ! ! ! ! ! ! & 

!!! BASRRW. B2S - Read records from one remote file !!! & 

! ! ! and write them to another ! ! ! & 

! ! ! ! ! ! . & 

!!! To task build, edit the task build command file !!! & 

! ! 1 and the ODL file created by the build. ! ! ! & 

! ! ! ! ! ! & 

! ! ! 1) Add the lines ! ! ! & 

! ! ! ACTFIL=4 ! ! ! & 

!!! EXTSCT=$$FSR1 : 10000 !!! & 

!!! to the task build command file. !!! & 

! ! ! ! ! ! & 

! ! ! 2 ) Append ! ! ! & 

! ! ! -NETLIB-NETLB2 ! ! ! & 

!!! to the USER: line of the ODL file. !!! & 

! ! ! ! ! ! & 

!!! 3) Add the lines !!! & 

!!! NETLIB: . FCTR LB : [ 1 , 1 ] NETFOR/LB !!! & 

!!! NETLB2: . FCTR LB : [ 1 , 1 ]NETFOR/LB : NFAFSR !!! & 

! ! ! to the ODL file. ! ! ! & 



20 ! ! I Define array constants 

DIM IARRAY%(255%) , IS 

\ NULL$ = STRING$(1%,0%) 

30 !!! Define constants !!! 

I CHARS $ = "AVF" 
\ OPNLUN% = 7% 

\ COUNT% = 2% 



'%(i%) ,MSTAT%(2%) & 
! Define maximum string lengths & 
! Define maximum string lengths & 

S> 

! Mode, type, carriage control & 
! Network OPEN LUN & 
! Max. # of active logical links& 
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\ MBXFLG% = 1 ! Long connect block flag & 

\ INPLUN% = 1% ! Input file LUN & 

\ OUTLUN% = 2% ! Output file LUM & 

\ EOF% = 20519% ! End of file status return & 

\ FALSE% = 0% ! Flag indicating FALSE & 
\ TRUE% = -1% ! Flag indicating TRUE 

40 INPUT "Remote node name (6 char, max . ) " ;NODNAM$ & 

\ IF LEN(N0DNAM$)>6% THEN PRINT & 

"Node name too long, please re-enter" & 

\ PRINT \ GO TO 40 & 
ELSE NODNAM$ = NODNAM$+NULL$ ! Form ASCIZ nodename 

50 INPUT "User ID (39 char. max.)";UID$ ! Get user ID & 

\ IF LEN(UID$)>39% THEN PRINT & 

"User ID too long, please re-enter" & 
\ PRINT \ GOTO 50 

60 INPUT "Password (39 char. max.)";PAS$ ! Get password & 

\ IF LEN(PAS$)>39% THEN PRINT & 

"Password too long, please re-enter" & 
\ PRINT \ GOTO 60 

70 INPUT "Account number (39 char. max.)";ACC$ ! Get account £< 

\ IF LEN(PAS$)>39% THEN PRINT & 

"Account number too long, please re-enter" & 
\ PRINT \ GOTO 70 

80 !!! Form ASCIZ IDENT string for remote file opens !!! & 
\ IDENT$ = UID$+NULL$+PAS$+NULL$+ACC$+NULL$ 

90 INPUT "Input file (64 char. max. ) " ; IFIL$ ! Get inp file & 

\ IF LEN( IFIL$)>64% THEN PRINT & 

"Input filename too long, please re-enter" & 

\ PRINT \ GOTO 90 & 
ELSE IFIL$=IFIL$+NULL$ ! Form ASCIZ filename 

100 INPUT "Output file (64 char. max. ) " ;OFIL$ ! Get out file & 

\ IF LEN(OFIL$)>64% THEN PRINT & 

"Output filename too long, please re-enter" & 

\ PRINT \ GOTO 100 & 
ELSE OFIL$=OFIL$+NULL$ ! Form ASCIZ filename 

110 !!! Open access to network - 2 links, long connect block!!! & 

CALL OPNNTW BY REF(OPNLUN% , ISTAT% ( ) ,MSTAT% ( ) ,CCUNT% & 

,,MBXFLG) & 

\ LOCI = 1 ! Origin of CALL for subroutine & 
\ GOSUB 250 ! Check status 

120 !!! Open remote file for input. !!! & 

CALL OPRNFW BY REF ( INPLUN% , I STAT% ( ) , NODNAM$ , IDENT$ , IFI L$ , S< 

ICHARS$,LNTH%,BLOCK%) ! Open remote file for input & 

\ LOCI = 2 ! Origin of CALL for subroutine & 
\ GOSUB 250 ! Check status 

130 !!! Open remote file for output. !!! & 

CALL OPWNFW BY REF (OUTLUN% , I STAT% ( ) , NODNAM$ , IDENT$ , OFI L$ , & 



(continued on next page) 
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ICHARS$,LNTH%,BLOCK%) ! Open remote file for output & 
\ LOCI = 3 ! Origin of CALL for subroutine & 

\ GOSUB 250 ! Check status 

140 !!! MAIN LOOP - read from input file !!! & 

! ! ! and write to output file ! ! ! & 

FOR I%=1% TO 100% 

150 CALL GETNFW BY REF( INPLUN% , ISTAT% ( ) , 256% , IARRAY% ( ) ) & 

! Read a record from input file 

160 IF ISTAT%(0%)<>1% AND ISTAT% ( 1% ) <>EOF% THEN 210 & 

! If error, print message & 
ELSE LNTH%=ISTAT%(1%) ! Save no. of bytes transferred 

170 ! ! ! Check for eof ! ! ! & 

IF ISTAT%(0%)<>1% AND ISTAT% ( 1% ) =EOF% THEN EOFFG%=TRUE% & 
ELSE EOFFG%=FALSE% ! Set flag if end of file 

180 IF EOFFG%=TRUE% THEN 230! IF END OF FILE, CLOSE FILES & 

ELSE CALL PUTNFW BY REF(OUTLUN% , ISTAT% ( ) , LNTH% t 
,IARRAY%()) ! Write record 

190 IF ISTAT%(0%)<>1% AND ISTAT( 1% ) <>EOF% GO TO 220 & 

ELSE A%=1% ! If unsuccessful, print message 

200 NEXT 1% I Terminate loop 

210 ! ! ! Read error occurred ! ! ! & 

PRINT "Read error. Status = ISTAT% ( 0% );","; ISTAT% ( 1% ) & 
\ GO TO 230 ! Close both files 

220 ! ! ! Write error occurred ! ! ! & 

PRINT "Write error. Status = ISTAT% ( 0% );","; ISTAT% ( 1% ) 

230 ! ! ! Close files ! ! ! & 

FOR J%=1% TO 2% ! Close files 1 and 2 & 

\ CALL CLSNFW(J%, ISTAT%( ) ) ! Close each file & 

\ NEXT J% ! Terminate loop & 

\ IF EOFFG%<>TRUE% THEN 240 ! If flag not true, transfer notS. 

! successful & 

ELSE PRINT "End of file reached. File closed" & 

! Indicate transfer successful 

240 GOTO 270 ! Branch to end 

250 !!! Subroutine to check status on completion of OPEN calls !!! & 

IF ISTAT%(0%)=1% THEN 260 ! If success, just return & 

ELSE PRINT "Open error. Status = "; ISTAT% ( 0% );","; ISTAT% ( 1% ) £< 

\ PRINT "Loc = ";L0C1 ! Origin of call & 

\ GO TO 270 ! Quit if unsuccessful 

260 RETURN ! Exit from subroutine 

270 END ! End execution 
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3.10 FORTRAN Task Control 



This section contains descriptions and usage guidelines for the FORTRAN task 
control calls summarized in Table 3-4. Task control allows you to run or abort 
specific tasks according to time schedules that you define in a DECnet call. 

Before you issue any of these calls you must access the network by issuing an 
OPNNTW call. When you complete task control operations, you must issue the 
CLSNTW call to stop accessing the network. 

3.10.1 Waiting for Requests 

All calls are synchronous and pass control back to the user task only after the 
operation completes. 

Table 3-4: FORTRAN Task Control Calls 



Call Function 



ABONCW Abort an executing task or cancel a schedule task 

BACUSR Build account and user ID information area 

RUNNCW Execute an installed task in a remote node 



3.10.2 RSX Remote Task Control Utility 

In order for these calls to execute successfully, the RSX Remote Task Control util- 
ity (TCL) must be installed on the remote node. If TCL is not installed, the call 
completes with an error. 
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ABONCW 
ABONCW 

(Abort an Executing Task or Cancel a Scheduled Task) 

3.10.3 ABONCW — Abort an Executing Task or Cancel a Scheduled Task 
Use: 

Call ABONCW to abort an executing task or cancel a scheduled task. 
Format: 

CALL ABONCW {lun\status\,ndsz,ndnm,passwdsiz,passwd, 
tsksiz, tsknam , [ident] , [mask]) 

Arguments: 

lun 

specifies an integer variable or constant and must be a logical unit number 
not currently in use. 

* status 

specifies an integer array containing the following completion status infor- 
mation on return from ABONCW: 

status{\) Returns an error/completion code 

status{2) If the error code in status{l) indicates a network reject (-7), 
status (2) contains the disconnect or reject reason code. Refer 
to Appendix A. Otherwise, status(2) contains a directive error 
code (if status{\) is -40) or null value (0). 

ndsz 

specifies an integer variable or constant containing the node name length in 
bytes. 

ndnm 

specifies a 1- to 6-element byte array containing the name of the target node. 
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passwdsiz 

specifies an integer variable or constant containing the password length in 
bytes. 

passwd 

specifies an array containing a user password with which to gain access to 
the remote system. Specify an array size consistent with the connect block 
size that you specified in the OPNNT call. The password can have 1-8. bytes 
in a short connect block, or 1-39. bytes in a long connect block. 

A privileged password lets a user abort any task running on the remote node 
without specifying the ident parameter. A nonprivileged password lets a 
user abort a task only by specifying the correct parameter. 

tsksiz 

specifies the remote task name length in bytes. 
tsknam 

specifies a 1- to 6-element byte array containing the name of the remote task 
to abort or cancel. 

* ident 

specifies an integer variable containing the negated task control block 
address of the remote task. This value is returned to the parameter of 
the RUNNCW call when the RUNNCW call completes. This argument is 
optional for a user with a privileged password. 

* mask 

indicates how ABONCW is used. This argument is optional. 

Omitting the mask argument or specifying a value of aborts only the exe- 
cuting task that the call specifies. Specifying the value 1 cancels the resched- 
uling of the specified task and continues execution of the current active task. 
Specifying a value greater than 1 aborts the executing task and cancels the 
rescheduling of the task. 



FORTRAN, COBOL, and BASIC-PLUS-2 Programming Facilities 



3-153 



ABONCW 

Error/Completion Codes: 

1 The call completed successfully. 

- 1 System resources needed for the logical link are not available. 

-7 The connection was rejected by the network. Refer to Appendix A. 

-8 A logical link has already been established using this LUN. 

-9 The task is not a network task: OPNNT did not execute successfully. 

-2 1 The requested task is not installed on the remote node. 

-23 An ABONCW was issued for a task that was not active . 

-24 A privileged violation has occurred. You are not a privileged user, and 
you are attempting an ABONCW for a task with improper identification. 

-25 An ABONCW was issued for a task that either was being loaded into or 
was exiting from the remote node. 

-40 A directive error has occurred. Directive error codes are defined in the 
RSX-1 IM/M-PLUS Executive Reference Manual. 
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BACUSL 

(Build Account and User ID Information Area (Long)) 
3.10.4 BACUSL — Build Account and User ID Information Area (Long) 
Use: 

Call BACUSL in the source task to build the user ID and account areas of the out- 
going connect block for task control programming. BACUSL supports 3 9. -charac- 
ter user IDs and accounts. 

BACUSL's function is similar to BACCL's, but you do not specify a password with 
BACUSL. Instead, you include the password with the ABONCW or RUNNCW call. 

If you have defined an alias node name that includes explicit access control infor- 
mation, or use proxy access, you need not call BACUSL. 

Format: 

CALL BACUSL ([status] , [usersz, user] , [accnosz,accno]) 

Arguments: 

* status 

specifies an integer variable. On return from BACUSL, this optional argu- 
ment is set to .TRUE.(-l) if the call completed successfully. It is set to 
. FALSE. (0) if one of the arguments to BACUSL is invalid. 

usersz 

specifies an integer variable or constant containing the user ID length in 
bytes. 

user 

specifies a 1- to 39. -byte array containing the user ID. The arguments usersz 
and user are paired optional arguments. Include both or omit both. 

accnosz 

specifies an integer variable or constant containing the length in bytes of the 
account number. RSX target systems do not use this argument. 
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accno 

specifies a 1- to 3 9. -byte array containing the account number. The accnosz 
and accno arguments are paired optional arguments. Include both or omit 
both. 
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BACUSR 

(Build Account and User ID Information Area (Short)) 
3.10.5 BACUSR — Build Account and User ID Information Area (Short) 
Use: 

Call BACUSR in the source task to build the user ID and account areas of the out- 
going connect block for task control programming. BACUSR supports 16. -charac- 
ter user IDs and accounts. 

BACUSR's function is similar to BACC's, but you do not specify a password with 
BACUSR. Instead, you include the password with the ABONCW or RUNNCW 
call. 

If you have defined an alias node name that includes access control information, 
or use proxy access, you need not call BACUSR. 

Format: 

CALL BACUSR ([status] , [usersz, user] , [accnosz,accno]) 

Arguments: 

* status 

specifies an integer variable. On return from BACUSR, this optional argu- 
ment is set to .TRUE.(-l) if the call completed successfully. It is set to 
. FALSE. (0) if one of the arguments to BACUSR is invalid. 

usersz 

specifies an integer variable or constant containing the user ID length in 
bytes. 

user 

specifies a 1- to 16. -byte array containing the user ID. The arguments usersz 
and user are paired optional arguments. Include both or omit both. 

accnosz 

specifies an integer variable or constant containing the length in bytes of the 
account number. RSX target systems do not use this argument. 
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accno 

specifies a 1- to 16. -byte array containing the account number. The accnosz 
and accno arguments are paired optional arguments. Include both or omit 
both. 
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RUNNCW 

(Execute an Installed Task in a Remote Node) 

3.10.6 RUNNCW — Execute an Installed Task in a Remote Node 

Use: 

RUNNCW allows you to execute an installed task in a remote node using any or all 
of the following options: 

■ Execute the task immediately. 

■ Schedule the task for execution at some future time. 

■ Schedule the task for periodical execution based on predefined time sched- 
ules. 

Format: 

CALL RUNNCW {lun , [status] , ndnm ,passwdsz,passwd, tsksz, tsknam,[ident] , 
[uic] , [smg,snt] , [rmg, rnt]) 

Arguments: 

lun 

specifies an integer variable or constant and must be a logical unit number 
not currently in use. 

* status 

specifies an integer array containing the following completion status infor- 
mation on return from RUNNCW: 

status( 1 ) Returns an error/completion code 

status(2) If the error code in status{\) indicates a network reject (-7), 
status (2) contains the disconnect or reject reason code. Refer 
to Appendix A. Otherwise, status{2) contains a directive error 
or is not used. 
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ndsz 

specifies an integer variable or constant containing the node name length in 
bytes. 

ndnm 

specifies a 1- to 6-element byte array containing the name of the target node. 
passwdsiz 

specifies an integer variable or constant containing the password length in 
bytes. 

passwd 

specifies an array containing a user password with which to gain access to 
the remote node. Specify an array size consistent with the connect block size 
that you specified in the OPNNT call. The password can have 1-8. bytes in a 
short connect block, or 1-39. bytes in a long connect block. 

A privileged password lets you run a task under any user identification code 
on the remote node. A nonprivileged password lets you run a task under 
only the UIC assigned to you. 

tskstz 

specifies an integer variable or constant containing the remote task name 
length in bytes. 

tskname 

specifies a 1- to 6-element byte array containing the name of the remote task 
to execute. 

* ident 

specifies an integer variable containing the negated task control block 
address of the remote task when RUNNCW completes. ABONCW uses this 
value. If you do not plan to cancel or abort this task later, you can omit this 
argument. 

uic 

specifies a 2-byte array containing the group and user codes under which the 
task runs on the remote node. The first element of the array contains the 
user member code; the second element contains the user group code. This 
argument is optional with a privileged password. If a privileged user omits 
this argument, the task runs under its default UIC on the remote node. 
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smg 

specifies an integer variable or constant containing the schedule delta magni- 
tude. The value of this optional argument is the difference in time from the 
issuance of the call to the time the task is to run at the remote node. 

This argument is used with the following argument, snt, which specifies the 
unit of time used to schedule the task (in hours, minutes, seconds, or ticks). 
In no case can the magnitude exceed 24 hours. 

snt 

specifies an integer variable or constant containing the schedule delta unit. 
This argument is a code identifying the time unit specified with the smg 
argument. The time unit codes are as follows: 

Code Description 

1 Ticks: A tick occurs for each clock interrupt and depends on the type 
of clock installed in the system. 

Line frequency clock: The tick rate is either 50 or 60 per second and 
corresponds to the powerline frequency. 

Programmable clock: A maximum of 1000 ticks per second is avail- 
able. The exact rate is determined at system generation. 

2 Seconds 

3 Minutes 

4 Hours 
rmg 

specifies an integer variable or constant containing the reschedule delta mag- 
nitude. The reschedule interval is the difference in time from task initiation 
to the time the task is to be reinitiated on the remote node. The task is exe- 
cuted each time the elapsed time equals the reschedule magnitude specified 
in this argument. If this time interval elapses and the task is still active, no 
reinitiation request is issued. However, a new reschedule interval is started. 

This argument is used with the following argument, rnt, which specifies the 
unit of time used to reschedule the task (in hours, minutes, seconds, or 
ticks). In no case can the magnitude exceed 24 hours. 
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rnt 



specifies an integer variable or constant containing the reschedule delta unit. 
This argument is a code identifying the time unit to use with the delta magni- 
tude specified in the rmg argument. 



■ If you omit the smg, snt, rmg, and rnt argu- 
ments, the task is executed immediately. 

■ If you specify smg and snt, but omit rmg and 
rnt, the task is executed once at the scheduled 
time. 

■ If you specify rmg and rnt, but omit smg and 
snt, the task is executed immediately and again 
each time the reschedule delta time has elapsed. 

■ You can specify all four arguments. For exam- 



CALL RUNNCW {lun, status, ndsz,tsksiz,tsknam. 



specifies that the task runs for the first time in 
one hour and then every four hours after that. 



NOTE 



pie: 



m/c, 1,4,4,4) 



Error/Completion Codes: 



1 



The call completed successfully. 



-1 



System resources needed for the logical link are not available. 



-7 



The connection was rejected by the network. Refer to Appendix A. 



-8 



A logical link has already been established using this LUN. 



-9 



The task is not a network task: OPNNT did not execute successfully. 



-20 



There is insufficient dynamic memory on the remote node. 



-21 



The requested task is not installed on the remote node. 
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-22 RUNNCW has an invalid time parameter . 

-23 An RUNNCW call was issued without scheduling parameters for a task 
that is already active. 

-24 A privileged violation has occurred. You are not a privileged user, and 
you are attempting to issue a RUNNCW under a UIC different from the 
UIC to which you are assigned on the remote node. 

-26 A RUNNCW was issued under an invalid UIC (for example, [1,0] or 
[0,11). 

-40 A directive error has occurred. Directive error codes are defined in the 
RSX-1 IM/M-PL US Executive Reference Manual. 
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3.10.7 FORTRAN Task Control Programming Example 



The RUNABO.FTN program uses DECnet task control calls to run or abort a task 
on a specified local or remote node. After executing your task control request, the 
program prompts you to enter another request to run or abort the associated task. 
When you finish entering task control requests, press ( ctrl/z ) to exit from the 
request-prompting loop and stop the program. 

Before running RUNABO.FTN, you must install the TCL task on the target node. 
This programming example is included in your tape or disk kit. 



c 

C RUNABO.FTN - Run or abort a task installed on remote node 

C 

C 

C Copyright (C) 1983, 1985, 1986, 1987 by 

C Digital Equipment Corporation, Maynard, Mass. 

C 

C 

C This software is furnished under a license and may be used and copied 
C only in accordance with the terms of such license and with the 
C inclusion of the above copyright notice. This software or any other 
C copies thereof may not be provided or otherwise made available to any 
C other person. No title to and ownership of the software is hereby 
C transferred. 
C 

C The information in this software is subject to change without notice 
C and should not be construed as a commitment by Digital Equipment 
C Corporation. 
C 

C Digital assumes no responsibility for the use or reliability of its 

C software on equipment which is not supplied by Digital. 

C 

C 

C This program illustrates the DECnet RSX task control routines. 
C 

C To task build, use the following command string: 
C 

C >TKB RUNABO,RUNABO=RUNABO,LB: [1,1]NETF0R/LB,F4P0TS/LB 
C 

C Note: The TCL task must be installed on the specified node. 

C 

C 

LOGICAL*! ANSWER, RUN, ABO, TARTSK( 6) ,TARN0D(6) ,PASSWD(8) ,USERID(16) 
LOGICAL*! ACCNT(16) 
INTEGER STATUS { 2 ), STAT 
INTEGER* 2 MSTAT ( 3 ) , I DENT 
DATA RUN/ 'R'/, ABO/ 'A'/ 

(continued on next page) 
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c 

C Create the network data queue 
C 

CALL OPNNTWd, STATUS, MSTAT) 

IF (STATUS(l) .NE. 1) WRITE ( 5 , 8 ) STATUS ( 1 ) 

C 

C Prompt for target node and target task 
C 

10 WRITE(5,1) 

1 FORMAT (5X,$' Enter target node: ') 
READ{5,2,END=999) ICNT1,TARN0D 

2 FORMAT ( Q, 16 Al) 

C 

WRITE( 5 , 3 ) 

3 FORMAT ( 5X, $' Enter target task: ') 
READ(5,2,END=999) ICNT2,TARTSK 

C 

C Prompt for access control information 
C 

WRITE(5,50) 
50 FORMAT( 5X, $• Enter target user ID: ') 
READ ( 5 ,2 ,END=999) ICNT4 ,USERID 

C 

WRITE(5,4) 

4 FORMAT ( 5X, $' Enter target password: ') 
READ (5,2,END=999)ICNT3,PASSWD 

C 

WRITE( 5, 11) 

11 FORMAT ( 5X, $' Enter target account number: ') 
READ (5,2,END=999) ICNT5,ACCNT 

C 

WRITE (5, 6) 

6 FORMAT ( 5X, $' Enter RUN (R) or ABORT (A): ') 
READ (5,7, END= 999 ) ANSWER 

7 FORMAT (Al) 

C 

C Decide whether to call BACUSR 
C 

IF (ICNT4 .EQ. .AND. ICNT5 . EQ . 0) GO TO 70 

CALL BACUSR ( STAT , I CNT4 , USERI D , ICNT5 , ACCNT ) 
IF (STAT .EQ. .TRUE.) GO TO 70 
WRITE(5,80)STAT 
80 FORMAT (' Error building connect block ') 
GOTO 10 

C 

C Decide whether to run or abort the task 
C 

70 IF (ANSWER .EQ. ABO) GOTO 20 

IF (ANSWER .EQ. RUN) GOTO 30 
GOTO 999 

C 

C Abort the task and print status 
C 

20 WRITE (5,100) 

100 FORMAT (5X,$'IDENT of task to abort (0 if password is privileged): *) 

READ (5,110)IDENT 
110 F0RMAT(I6) 

CALL ABONCW ( 2 . STATUS , ICNTl . TARNOD . ICNT3 . PASSWD . ICNT2 , TARTSK , IDENT ) 

(continued on next page) 
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c 

WRI TE ( 5 , 8 ) STATUS (1 ) 
8 FORMAT (' Status = ',17) 
GOTO 10 

C 

C Run the task and print status. 
C 

30 CALL RUNNCW{2 ,STATUS, ICNT1,TARN0D, ICNT3,PASSWD, ICNT2 , TARTSK , IDENT) 
WRITE {5,8)STATUS{1) 

IF (STATUS(l) .EQ. 1) WRITE (5,90) IDENT 
90 FORMAT (' The IDENT is ',16) 
GOTO 10 
999 STOP 
END 



3-166 



DECnet-RSX Programmer's Reference Manual 



4 



DLX Ethernet Programming Facilities 



The Direct Line Access Controller (DLX) gives application programs a direct 
interface to the data link, bypassing the standard DECnet user interface. With 
DLX, you can communicate with DECnet or non-DECnet based systems. Because 
DLX does not offer higher-level DECnet services, such as routing and guaranteed 
delivery, it can give high performance in network applications. DLX also lets you 
build customized user-level protocols that best suit your applications. 

To use DLX, you issue queued input/output (QIO) calls to the NX: device. Your 
DLX program uses the Ethernet and/or IEEE 802.3 standard. It can communicate 
with a DLX program or the equivalent data link function on an adjacent DECnet- 
RSX or non-DECnet node. Your DECnet-RSX node can simultaneously run multi- 
ple DECnet and DLX tasks, each possibly communicating with different remote 
nodes. 

DLX is automatically built for DECnet-RSX- 11 M-PLUS and DECnet-Micro/RSX 
systems; it is optional for DECnet-RSX- 1 IM. It is also optional for RSX-1 IS sys- 
tems, but is required on a host for down-line loads and up-line dumps from RSX- 
1 IS systems. You can use DLX to communicate over all devices that DECnet-RSX 
supports. For information on programming for point-to-point and multipoint 
lines, refer to Chapter 5. 

Throughout this chapter, the term "the Ethernet" refers to the physical transmis- 
sion media (cables and controllers) and data link level software that provides 
access to the physical media according to a Carrier Sense Multiple Access with 
Collision Detection (CSMA/CD) protocol. The physical channel may be broad- 
band or baseband. The Ethernet can transmit frames in formats that conform to 
either the Ethernet standard or the IEEE standards. 
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4.1 Preparing the System 



Before your system runs a DLX program, the DLX process must be loaded and the 
line set. 

The person in charge of network or system management installs the network, 
usually by executing a command file that contains the command for loading DLX. 
When DLX is loaded, it resides in the common partition NT. DLX. 

The network manager also sets the line, either by answering Yes to the NETGEN 
question that asks about marking the line for load, or by issuing the Network Con- 
trol Program (NCP) SET LINE command. For information on using NCP to set the 
line, refer to the DECnet-RSX Guide to Network Management Utilities. 

4.2 Including Higher-Level Services 

DLX programming requires a thorough knowledge of MACRO- 11 assembly lan- 
guage and experience in writing real-time application programs. 

Since DLX bypasses the higher levels of DECnet you lose the services at those 
levels and must, therefore, include them in your application. Your programs must 
provide the following: 

Flow control DLX does not support flow control for data transfer. The 

DLX programs that run on different nodes must therefore 
synchronize with each other before transferring data. If 
the tasks are unsynchronized, data can be lost. 

Error recovery The DLX software reports errors, but your program must 

include error recovery procedures. 

Data segmentation When transmitting data, your program must segment it; 

the buffer size must be appropriate to the controller 
devices on the communicating systems. For information 
on appropriate buffer sizes, consult your network man- 
ager. 

Note that all incoming and outgoing DLX and DECnet messages are buffered in a 
shared network buffer pool. Your network manager can increase the size and/or 
number of buffers to maintain good throughput performance, if necessary. For 
information on displaying and setting buffer sizes, refer to the DECnet-RSX net- 
work management documentation. 

Also note that you must use the /PR:0 switch to task build your DLX programs. 
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4.2.1 Using DLX Resources 

DLX provides macros and QIOs to use in your application. 

The DECnet macro library, NETLIB.MLB, defines the offsets and macros that DLX 
QIOs use. During NETGEN, this library is transferred to your system. The defini- 
tion macro DLXDF$ contains definitions for offsets and macros. 



Your program must issue an .MCALL statement and explicitly invoke the defini- 
tion macro, as in the following example: 

.MCALL DLXDF$ ; extract from macro library 
DLXDF$ ; define DLX symbols 

You can use the following QIO functions in Ethernet programming: 



lO.XOP Open a port on the Ethernet device. This lets your program 

treat the Ethernet as a device that your QIOs control. 

lO.XSC Set characteristics for your Ethernet port. You can set such port 

characteristics as the frame format to use, the addresses from 
which you want to receive messages, and so forth. 



lO.XGC Get characteristics of the port. 

lO . XTM Transmit a message . 

lO.XRC Ready the port to receive a message. 

lO.XCL Close the port and relinquish use of the controller. 



4.3 Using DLX to Access the Ethernet 

An Ethernet data link on a single Ethernet controller supports multiple concur- 
rent users. Each station represents an available port onto the Ethernet channel. 

Because multiple users simultaneously access the Ethernet channel, your program 
must use addressing mechanisms that ensure delivery of messages to the correct 
recipient. Any message that you transmit on the Ethernet must include an 
Ethernet address that identifies the target node. The message must also include an 
additional identifier that directs the message to the correct user on the target 
node; this identifier varies according to the frame format you choose to use. DLX 
lets you choose to build frames according to the Ethernet or IEEE 802.3 standard, 
or both. 
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The Ethernet format is a proprietary standard that belongs to Digital Equipment, 
Intel, and Xerox corporations. The IEEE 802.3 format, in contrast, is a standard 
for multi-vendor networking. To communicate with other Digital nodes, you 
might have applications that use the Ethernet frame format, and to communicate 
with non-Digital nodes, you might use the 802.3 frame format. Any single appli- 
cation can send and receive both types of frames. Later sections of this chapter 
describe how to set up the Ethernet address and use each frame format. 

This chapter covers the following topics: 

■ Synchronizing DLX programs 

■ Using physical and multicast addressing 

■ Setting up the Ethernet address 

■ Using characteristics buffers 

■ Processing Ethernet-format frames 

■ Processing 802. 3-format frames 

■ DLX QIOs 

References throughout the chapter to the IEEE standard are to the information in 
two publications listed in the Preface to this manual: Carrier Sense Multiple 
Access with Collision Detection (CSMA/CD) Access Method and Physical Layer 
Specifications (802.3), and Logical Link Control (802.2). 

4.3.1 Synchronizing DLX Programs 

In writing your DLX application, you must synchronize the programs on both 
nodes to ensure that they can cooperate. Both communicating nodes must do the 
following: 

■ Open the line, specifying the same frame format (Ethernet or 802 . 3). 

■ Specify what frames you want the port to send and receive. For Ethernet 
frame format, both nodes must enable the port to send and receive frames 
with the same protocol type. For 802.3 frame format, both nodes must 
enable the port to send and receive frames with the same Subnetwork Access 
Protocol (SNAP) identifier, or to receive frames with each other's Service 
Access Point (SAP). Later sections explain how you use protocol types, 
SNAPS, and SAPs. 
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■ The nodes must then coordinate their transmission and reception. The 
receiving node must have a receive QIO pending before the sending node 
transmits. 

4.3.2 Using Physical and Multicast Addressing 

You can transmit and receive messages over the Ethernet in physical or multicast 
address mode. Physical addressing sends messages to a single destination node. 
Multicast addressing sends messages to a group of nodes. If each node in the 
group enables reception of messages with a given multicast address, a single trans- 
mission to that address can reach all nodes in the group. 

To send messages in physical mode, you specify the destination address in a trans- 
mit request. If the target node is a non-DECnet node, you send messages to its 
Ethernet hardware address. If the target node is a DECnet node, you send mes- 
sages to its Ethernet physical address. The Ethernet physical address is derived 
from the node address. The next section explains how to set up the Ethernet 
address for remote DECnet nodes. You receive any physical mode messages that 
other nodes address to your Ethernet hardware address on a non-DECnet node, 
or to your Ethernet physical address on a DECnet node. You need not specially 
enable these addresses. 

To send multicast messages, you simply specify the Ethernet multicast address as 
the destination on a transmit operation. Any node can send messages to any 
multicast address. To receive messages sent to a multicast address, you specify the 
address when setting port characteristics with lO.XSC. You can receive any num- 
ber of multicast addresses. 

The multicast address for Digital Equipment Corporation customer use is 09-00- 
2B-00-00-0F. In a Digital-only environment, you can use other numbers that 
fall outside the range of those reserved for internal Digital use. In a multi-vendor 
environment, other multicast addresses might conflict with the other vendors' 
conventions. For more information on multicast addresses, refer to Appendix G. 

For a further description of Ethernet addressing, refer to DECnet-RSX Network 
Management Concepts and Procedures. 

4.3.3 Setting Up the Ethernet Address 

All messages on an Ethernet channel have one 48-bit Ethernet address that 
specifies the destination node and one that specifies the source node. While you 
need not supply your own (source) address when you transmit, you must always 
supply the destination address. 
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When sending messages to a DECnet node, you can derive the Ethernet address 
from the node address. The DECnet destination consists of 6 bytes. The first four 
bytes are standard, and contain the following octal values: 

Byte 252 
Byte 1 
Byte 2 4 
Byte 3 

For bytes 4 and 5, use an octal version of the area number and node number, and 
format them as follows: 

Bits 10 to 1 5 DECnet area number (The default area number is 1 .) 
Bits to 9 DECnet node number 

For example, you convert DECnet node addresses of 1.154 and 4.153 to destina- 
tion addresses as follows: 

Node Address Destination Address 

(Decimal) (Octal) Hexadecimal Equivalent 

1.154 252,0,4,0,4,232 AA-00-04-00-04-9A 

4.153 252,0,4,0,20,231 AA-00-04-00- 10-89 



To send messages to a non-Digital node, you must know the destination hardware 
address. Be sure to program the address into the correct bytes. For example, if the 
destination address, in hexadecimal notation, is 08-00- AB-OO-AF-FE, enter the 
hexadecimal values as follows: 



00 


08 


GO 


AB 


FE 


AF 



LKG-1 039-87 
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4.3.4 Setting Up a Characteristics Buffer 

Most of the DLX QIOs let you specify or read characteristics for the QIO. Some 
characteristics affect the Ethernet port; others affect a specific transmit or receive 
operation. You can set characteristics for the port when you issue lO.XOP to 
open the port and by issuing the Set Characteristics QIO. You can read the port 
characteristics by issuing the lO.XGC (get characteristics) QIO. You can also set 
certain characteristics for each transmit (lO.XTM) and receive (lO.XRC) QIO. 

Some characteristics are required for a QIO; others are optional. A transmit QIO, 
for example, always requires that you supply the destination Ethernet address 
characteristic. 

To set or read characteristics, you create a characteristics buffer and enter the 
buffer's address and length as QIO parameters. One or more characteristics 
blocks in the buffer specify the characteristics to set or read. This chapter 
describes the various characteristics blocks for Ethernet programming in the sec- 
tion about processing Ethernet frames, and the characteristics for 802.3 program- 
ming in the section about processing 802. 3 frames. In addition, each QIO descrip- 
tion includes a description of the characteristics to use with that QIO. 

For example, you can specify that a port opens in Ethernet or 802.3 frame format 
when you issue the Open Port (lO.XOP) directive. You create a buffer that 
includes the frame format characteristics block, CC.FMO, into which you enter 
the frame format value. You then reference the buffer's address and length in the 
QIO. Once you have specified the frame format (Ethernet format is the default), 
you can then specify other format-specific characteristics. For 802.3 format, you 
can specify the 802.3 service class; for Ethernet format, you can specify the 
Ethernet protocol type. You append the blocks for these characteristics to the 
frame format block in the buffer. An example later in this section illustrates how a 
program opens a port for 802.3 format and specifies the service class. 

A characteristic that affects the port affects all data that the port handles, unless 
you override the characteristic on a specific transmit or receive QIO. In contrast, 
a characteristic that affects a transmit or receive request affects only the specific 
transmit or receive QIO. 

Characteristics blocks have a standard format in the first four fields. Table 4-1 
describes these fields. 
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Table 4-1 : The First Four Fields in a Characteristics Block 



Word 



Name 



Contents 



Use 



C.TYP 



C.DATI 



C.DATO 



C.STAT 



Characteristics 
type 



Size of 
data input 



Reserved for 
size of 
data output 



Reserved for 

characteristics 

status 



Identifies what characteristic 
the block contains information 
about. For example, CC.ADR in 
this field specifies a destination 
address block, CC.MCT 
specifies a multicast address 
block, and so on. 

Identifies the length, in bytes, 
of the characteristics data in the 
C.CHRL field. For example, if a 
CC.MCT block contains one 6- 
byte multicast address, this field 
contains a 6. 

Gives the length, in bytes, of 
any returned data on comple- 
tion of characteristics process- 
ing. Always put a zero (0) in 
this field. 

Contains a code indicating com- 
pletion status after characteris- 
tics block processing. Always 
put a zero (0) in this field. 
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The characteristics block for a single characteristic looks like this: 

CHARACTERISTICS 
BLOCK 

CHARACTERISTICS TYPE 
SIZE OF DATA INPUT 
RESERVED 
CHARACTERISTICS STATUS 
CHARACTERISTICS DATA 



LKG- 1040-87 

The fifth field, C.CHRL, contains the specific characteristics information. 



CTYP 

C.DATI 
C.DATO 
C.STAT 
CCHRL 
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You can append multiple characteristics blocks in a single characteristics buffer as 
follows: 

CHARACTERISTICS 
BUFFER 

BUFFER ADDRESS 



CHARACTERISTICS TYPE 



SIZE OF DATA INPUT 



RESERVED 



CHARACTERISTICS STATUS 



CHARACTERISTICS DATA 



CHARACTERISTICS TYPE 



SIZE OF DATA INPUT 



RESERVED 



CHARACTERISTICS STATUS 



CHARACTERISTICS DATA 



CHARACTERISTICS TYPE 



SIZE OF DATA INPUT 



RESERVED 



CHARACTERISTICS STATUS 



CHARACTERISTICS DATA 



C.TYP 
C.DATI - 
C.DATO 
C.STAT 
C.CHRL 



C.TYP 
C.DATI ■ 
C.DATO 
C.STAT 
C.CHRL 



C.TYP 

C.DATI 

C.DATO 

C.STAT 

C.CHRL 



BUFFEf 
LENGTI 
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The following program fragment uses a characteristics buffer in opening an 
Ethernet port. Before issuing the lO.XOP QIO, the program creates a characteris- 
tics buffer with two characteristics blocks. As an example, the first block requests 
802.3 frame format. With 802.3 frame format, the data link provides certain ser- 
vices if you request Class I service. The second block requests Class I service. The 
lO.XOP QIO then references the buffer that contains these characteristics blocks. 





.MCALL 


DLXDF$ 






DLXDF$ 




; Define DLX I/O codes and symbols 


PRTLUN 


= 1 




; Logical unit number of port 


PRTFLG 


= 1 




; Event flag for all port I/O 


DEVNM: 


.ASCII 


\UNA-0\ 


; Address of device name 


DEVLN 


= .-DEVNM 
.EVEN 




; Length of device name 


lOSB: 


.BLKW 


2 


; I/O status block 



; Characteristics buffer for open 

; This buffer contains a pair of characteristics blocks - one to 

; open the port for handling 802.3 frames and the other to 

; request Class I service for the 802.3 port. 

OPNCHB : 



; Define 


frame 


format for open 






.WORD 


CC.FMO 


C.TYP Characteristic type 




.WORD 


2 


C.DATI Frame format takes 2 bytes 




.WORD 





C.DATO To be returned 




.WORD 





C.STAT To be returned 




.WORD 


NX$802 


G.CHRL 802 frame format 


; Define 


Class 


I service for open 




.WORD 


CC.SCO 


C.TYP Characteristic type 




.WORD 


2 


C.DATI Service class takes 2 bytes 




.WORD 





C.DATO To be returned 




.WORD 





C.STAT To be returned 




.WORD 


NX$CLI 


C.CHRL 802 Class I service 


OPNCHL 


= . -OPNCHL 


Size of characteristics buffer 



; Directive parameter blocks 

OPNDPB QlOWl 

10 . XOP , PRTLUN , PRTFLG , , lOSB , , <DEVNM , DEVNML , OPNCHB , OPNCHL> 



In the line containing the lO.XOP call, OPNCHB specifies the address of the char- 
acteristics buffer and OPNCHL specifies its length. 

The order in which your program references the characteristics can be important. 
DLX processes the characteristics buffer sequentially, and some characteristics 
create prerequisite conditions that are prerequisites for other characteristics. For 
instance, if the previous example attempted to request Class I service without 
first requesting 802.3 frame format, an error would occur. 
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The DECnet-RSX Network Management Concepts and Procedures manual has 
more information on using Ethernet devices. For detailed information on 802.3 
frame formats, refer to the IEEE standard. The next sections describe special pro- 
cedures for processing Ethernet and 802.3 frame format. 

4.3.5 Processing Ethernet Frames 

This section describes special considerations for using Ethernet frame format on 
the Ethernet channel. 

All Ethernet frames contain a 1 6-bit identification number called an Ethernet pro- 
tocol type. When a message arrives at the controller, the protocol type identifies 
which port receives the frame. DLX applications that communicate across the 
Ethernet must always enable the same Ethernet protocol type. 

You enable the port to receive the protocol type by issuing an lO.XSC to set the 
port characteristics. You specify the protocol type in a CC.DST characteristic 
block, which lO.XSC references. Enable the protocol type after opening the port, 
but before receiving or transmitting messages with the protocol type. Specify an 
enabled protocol type in every transmit QIO and read it in every receive QIO. 

The protocol type for Digital Equipment Corporation customer use is 60-06. For 
more information on protocol type values, refer to Appendix G. 

When enabling an Ethernet protocol type, you can add the following information 
to the CC.DST characteristics block to further specify how the port handles the 
protocol: 

■ Protocol flags that specify modes for receiving and sending messages with 
the protocol type. 

■ Specific remote addresses to and from which the port will process messages 
with the protocol type. 

4.3.5.1 Setting Protocol Flags 

The characteristic block that you use to enable a protocol type has a field for pro- 
tocol flags. Protocol flags can do the following: 

■ Set the receipt mode for the protocol type to exclusive or default 

■ Request padding support for frames with the protocol type 

■ Disable the protocol type 
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Your Ethernet port can receive messages with a given protocol type in exclusive, 
default, or normal usage mode: 



Exclusive 
LFSEXC 



The application receives all messages with the protocol type. 



Default 
LFSDEF 



The application receives messages with the protocol type 
from any address that another application does not receive in 



Normal 



The application specifies the addresses from which to receive 
messages with the protocol type. 



For exclusive or default mode, you set the appropriate flag in the CC.DST charac- 
teristics block. Normal mode requires that you omit the flag and specify 
addresses in the characteristic block, as the following section describes. 

To request padding support, you can set the LF$PAD flag. Padding is a highly rec- 
ommended option for ensuring data integrity. On transmit operations, the device 
driver software pads each frame to the minimum Ethernet size; the actual data in a 
frame may therefore be less than the frame's physical length. With padding sup- 
port, however, the data link will prefix the actual data with a 2-byte length field 
on transmit and read the length field on receive. On receive, it strips the padding 
from the message before passing the message to your application. You must set 
the flag to get padding support when you enable a protocol. 

To disable a protocol type, set the LF$DIS flag. 

4.3.5.2 Specifying Protocol/Address Pairs 

To instruct the port to process the protocol type to and from certain addresses 
only, add the addresses to the characteristics block that enables the protocol type 
(CC.DST). To ensure communication among DLX programs on different nodes, 
each program enables the same protocol type. Each program pairs the protocol 
with the remote nodes' physical or multicast Ethernet addresses or sets the proto- 
col flag to receive in exclusive mode. 

Two or more users on a node can enable the same protocol or the same addresses, 
but only one user can enable any protocol/address pair. This prevents two pro- 
grams on a node from competing for the same frames. 
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4.3.5.3 Using Characteristics Blocks 



Table 4-2 lists the characteristics for Ethernet frame format according to the DLX 
function and QIO with which you use them. Within each function, the character- 
istics are listed alphabetically. Each QIO description later in this chapter has 
detailed information on the related characteristics. 

Table 4-2: Characteristics for Ethernet Frame Format 
Symbol & 

Value What It Does 

Open the Port (lO.XOP) 

CC. FMO Defines a single frame format for the port. 

(103) 

Set and Get Port Characteristics (lO.XSC and lO.XGC) 

CC.DST Enables the port to send and receive messages with a specified pro- 

(200) tocol type and pairs the protocol with addresses on a set character- 

istics operation; returns the protocol type and addresses on a get 
characteristics operation. 

CC.FRM Specifies a second frame format for the port on a set characteristics 

(202) operation; returns the second frame format on a get characteristics 

operation. 

Transmit and Receive (lO.XTM and lO.XRC) 

CC.ADR Sets the destination node address on transmit; returns the source 

( 1 00) node address on receive . 

CC.DAD Returns the destination address to which a received message was 

(102) sent. 

CC.FMM Sets the frame format of a message on transmit; returns the frame 

(105) format on receive. 

CC.PRO Sets the protocol type of a message on transmit; returns the proto- 

(101) col type on receive . 



4.3.6 Processing IEEE 802.3 Frames 

The Institute of Electrical and Electronics Engineers (IEEE) has defined the 802.3 
frame format for communicating over the Ethernet. You may choose to use 
802.3 frame format, especially for inter-vendor communications. Using 802.3 
format, a DLX program on a Digital node can communicate with a similar pro- 
gram on a Digital or non-Digital node. To use 802.3 frame format, familiarize 
yourself with the IEEE standard. 
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When you use 802.3 format, you must choose the 802.3 service class and address- 
ing mode to use. The next sections explain your choices. 

4.3.6.1 Specifying the Service Class 

The service class determines the level of service that the data link provides to 
your application. DECnet-RSX supports two 802.3 service classes: Class I and 
user-supplied service. 

Class I service lets your program perform IEEE 802 . 3 Type I operations and it sup- 
ports three frame types: 

UI Unnumbered information 

TEST Test 

XID System identification 

UI frames contain data to send and receive. TEST and XID frames verify that a 
node with which you want to communicate is up and running the correct soft- 
ware. The IEEE standard fully describes these frame types. 

With Class I service, the data link: 

■ Filters out all extraneous types of messages. 

■ Handles unsolicited XID and TEST messages from other nodes. 

■ Builds and strips frames, letting your program handle just the data in the 
frame without supplying or reading headers. 

Class I service also provides a group addressing capability described in a follow- 
ing section. 

With user-supplied service, your application can use any IEEE 802.3 frame types, 
but your application must build and strip them. Your program must also include 
routines for filtering out unwanted types of messages. 

You can specify Class I service when you open the port or set port characteristics 
for 802.3 format. The default service type is user-supplied. 

You must also choose to use either Service Access Points (SAPs) or Subnetwork 
Access Protocols (SNAPs) to identify your 802.3 frames. The next two sections 
describe SAPs and SNAPs. 
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4.3.6.2 Defining Service Access Points 

Service Access Points (SAPs) identify each application that accesses the Ethernet 
in 802.3 format. The destination Ethernet address identifies the target node for 
the message, and then the Destination SAP (DSAP) and Source SAP (SSAP) identify 
the destination and source application at the port. All 802.3 frames contain SAPs, 
which are therefore helpful in multi-vendor programming environments. 

With SAPs, you must define at least one Individual SAP (ISAP) for each 802.3 
application. The application's ISAP must be unique and exclusive. You then use 
lO.XSC to set the port characteristics to receive messages with the specified ISAP. 
On transmit, you supply the Destination SAP and Source SAP; on receive, you 
read the DSAP and SSAP. 

Each ISAP on a node identifies only one application, but each application can 
enable multiple SAPs. You might use different SAPs, for example, to identify dif- 
ferent functions that the application performs. 

With Class I service only, your application program can also enable one or more 
Group SAPs in addition to its individual SAPs. Group SAPs (GSAPs) let you send 
messages to a group of programs on a remote node. To define a program as a 
member of a group, the program sets the port characteristics to enable receipt of 
the GSAP. Any other application can then address messages to the entire group at 
once, simply by specifying the GSAP as the Destination SAP in a transmit. An 
application must enable at least one ISAP before receiving frames addressed to its 
GSAP. 

Each 802.3 frame has a control (CTL) field that specifies what type of data the 
frame contains. With SAPs, you must specify the contents of the CTL field on 
every transmit and read them on every receive. With Class I service, the control 
field can contain the value that specifies a UI, a TEST, or an XID frame. With user- 
supplied service, the field can contain a value that specifies any type of 802.3 
frame. 

4.3.6.3 Defining SNAP Protocol Identifiers 

Subnetwork Access Protocol (SNAP) identifiers provide an alternate identifica- 
tion mode for 802.3 frames. SNAP identifiers consist of 5 bytes. Because they are 
larger than SAPs, they let you address many more users on a single node, offering 
flexibility for uniquely identifying applications in a very large environment. 
SNAP identifiers might be preferable in an environment that consists only of 
Digital nodes. 
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To use SNAPS, you assign identical SNAP identifiers to communicating programs. 
You set characteristics to enable the port to transmit and receive messages with 
that SNAP identifier, using the CC.SNP characteristic with lO.XSC. Then you 
specify a message's SNAP identifier on transmit and read it on receive, using the 
CC.SNM characteristic with lO.XTM and lO.XRC. You need not specify the Desti- 
nation SAP, Source SAP, or CTL fields, as you would in simple SAP addressing. 
DLX automatically builds these fields with standard values when you specify a 
SNAP identifier. When the data link receives a frame with these standard DSAP, 
SSAP, and CTL values, it automatically proceeds to processing the SNAP identi- 
fier. 

When enabling a SNAP identifier, you can add the following information to the 
CC.SNP characteristics block to further specify how the port handles the proto- 
col: 

■ Protocol flags that specify modes for receiving and sending messages with 
the protocol type. 

■ Specific remote addresses to and from which the port will process messages 
with the protocol type. 

4.3.6.4 Setting Protocol Flags 

The characteristics block that you use to enable a SNAP identifier has a field for 
protocol flags. Protocol flags can do the following: 

■ Set the receipt mode for the protocol type to exclusive or default 

■ Disable the protocol type 

Your Ethernet port can receive messages with a given SNAP identifier in exclu- 
sive, default, or normal usage mode: 

Exclusive The application receives all messages with the SNAP identifier. 



LF$EXC 



Default 
LF$DEF 



The application receives messages with the SNAP identifier from 
any address that another application does not receive in normal 
mode. 



Normal 



The application specifies the addresses from which to receive 
messages with the SNAP identifier. 
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For exclusive or default mode, you set the appropriate flag in the CC.DST charac- 
teristics block. Normal mode requires that you omit the flag and specify 
addresses in the characteristic block, as the following section describes. 

To disable a SNAP identifier, set the LF$DIS flag. 

4.3.6.5 Specifying Protocol/Address Pairs 

To instruct the port to process the SNAP identifier to and from certain addresses 
only, add the addresses to the characteristics block that enables the protocol type 
(CC.SNP). To ensure communication among DLX programs on different nodes, 
each program enables the same SNAP identifier. Each program pairs the protocol 
with the remote nodes' physical Ethernet addresses or sets the protocol flag to 
receive in exclusive mode. 

Two or more users on a node can enable the same SNAP identifier or the same 
addresses, but only one user can enable any protocol/address pair. This prevents 
two programs on a node from competing for the same frames. 

Appendix G has information on the available SNAP identifiers. 

4.3.6.6 Using Ctiaracteristics Blocks 

Table 4-3 lists the characteristics for 802.3 frame format according to the DLX 
function and QIO with which you use them. Within each function, the character- 
istics are listed alphabetically. Each QIO description later in this chapter has 
detailed information on the related characteristics. 
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Table 4-3: Characteristics for 802.3 Frame Format 



Symbol & 

Value What It Does 



Open the Port (lO.XOP) 

CC.FMO Defines a single frame format for the port. 

(103) 

CC.SCO Requests Class I service for the 802.3 port. 

(104) 

Set and Get Port Characteristics (lO.XSC and lO.XGC) 

CC.FRM With lO.XSC, enables or disables a second frame format; with 

(202) lO.XGC, returns the second frame format. 

CC.GSP With lO.XSC, enables or disables the port's processing of a specified 

(205) group SAP; with lO.XGC, returns information on enabled GSAPs. 

CC.ISP With lO.XSC, enables or disables the port's processing of a specified 

(204) individual SAP; with lO.XGC, returns information on enabled 

ISAPs. 

CC.MCT With lO.XSC, enables the port to receive messages with the speci- 

(201) fled multicast address; with lO.XGC, returns the enabled multicast 

address. 

CC.SNP With lO.XSC, enables or disables the port's processing of the speci- 

(206) fled SNAP protocol identifier; with lO.XGC, returns information on 
enabled SNAP protocols. 

CC.SRV With lO.XSC, requests Class 1 service; with lO.XGC, returns the 

(203) value for Class I service. 

Transmit and Receive (lO.XTM and lO.XRC) 

CC.ADR Sets a destination node address on transmit; returns the source node 

(100) address on receive . 

CC.CTM Specifies the contents of the control field (CTL) on transmit; returns 

(107) the contents of the control field on receive. 

CC.DAD Returns the destination address of an incoming frame on receive. 
(102) 

CC.FMM Specifies the frame format of a message on transmit; returns the 

(105) frame format of a message on receive. 

CC.SNM Specifies the SNAP protocol identifier for a message on transmit; 

(110) returns the SNAP protocol on receive . 

CC.SPM Specifies the Destination SAP/Source SAP pair for a message on 

(106) transmit; returns the DSAP/SSAP on receive. 
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4.4 DLXQIOs 



DLX requests conform to normal standards for RSX-11 QIOs, including logical 
unit numbers (LUNs), event flags, I/O status blocks, asynchronous system traps 
(ASTs), and parameter lists. According to RSX-11 standards, you can use any one 
of the three macro formats (see Chapter 2). You can use the QIO wait option 
(QIOW$) to suspend execution of the program until the call completes. 

The rest of this chapter describes the DLX QIOs. The descriptions are in the order 
in which you will probably use the QIOs. Note that the QIO descriptions include 
lists of codes for two distinct types of completion status: 

■ QIO completion status 

■ Characteristics completion status 

QIO completion status codes tell you that the QIO executed successfully or that a 
specific error occurred during execution. DLX returns the completion status to 
the 2 -word status block that you specify as the status parameter in the QIO's for- 
mat. IS. sue (1) is the standard success code. The codes for execution errors have 
an IE. prefix and three letters that represent a specific error. Each QIO description 
includes any QIO completion status codes you may get. 

Characteristics status codes tell you that the characteristics block was success- 
fully processed or that a specific error occurred during processing. DLX returns 
the status code to the characteristics block's status field, C.STAT. CS.SUC (1) is 
the code for success. The other codes have a CE. or CS. prefix and three variable 
letters representing specific status. Each characteristic description lists the status 
codes you can receive for that characteristic, and Appendix H provides more 
detailed information on each code. 

Note that the QIO can succeed even if the characteristics function encounters an 
error. For full completion status, check the contents of both the status block and 
C.STAT field. 
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lO.XOP 

lO.XOP 

(Open a Port) 

4.4.1 lO.XOP — Open a Port 
Use: 

Issue this QIO to create a port for DLX transmission and reception. The port is an 
I/O access path to the controller whose device ID you specify in arguments p4 
and p5. In response to this QIO, DLX scans the controller's port data base and 
associates an available port with the logical unit number (LUN) that you specify. 

The port will open for Ethernet frame format unless you use the p4 and p5 param- 
eters to specify 802.3 format. 

Format: 

QIO$ lO. XOF,lun,[efn]„[status],[asf\,<pl,p2,p3,\p4,p5] > 

Arguments: 

lO.XOP 

is the function code that opens a port. 
lun 

is the logical unit number associated with the port. 
efn 

is an optional event flag number set when the QIO completes. 
status 

is the address of an optional 2 -word status block that contains the QIO's comple- 
tion status in the low-order byte of the first word (see under "QIO Completion 
Status"). 

ast 

is the entry point into an optional user- written AST routine to execute after this 
QIO completes. 
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pi 

is the address of an ASCII string that identifies the controller on which to open the 
port. The string has the form dev-ctl, where dev is a device name, such as UNA or 
QNA, and ctl is the decimal value for the controller number. 

P2 

is the length of an ASCII string that identifies the controller on which to open the 
port. The string has the form dev-ctl, where dev is a device name, such as UNA or 
QNA, and ctl is the decimal value for the controller number. 

P3 

is a word argument that specifies the timeout value and port mode. The timeout 
value specifies how long to wait to receive a transmitted message. The low-order 
byte of the word designates the receive timeout value as follows: 

timeout = for no receive timer. 
timeout = <n> 

where n is the timer value in seconds. (The timer value n causes the timeout to 
have a range of w-1 to «.) 

p4 

is the address of the characteristics buffer. 
p3 is the length of the characteristics buffer. 

Characteristics Buffer: 

The characteristics buffer can contain the following blocks: 

CC.FMO Frame Format for Open 

CC.SCO Class I Service for Open 

The blocks must be in sequential order in the buffer; that is, the frame format 
characteristic must precede the service class characteristic. 

Refer to Appendix H for more information on the characteristics status codes. 
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CC.FMO (103) = Frame Format for Open 

This characteristic specifies a frame format for opening the port. You can 
specify one format. To use both Ethernet and 802.3 frame format, specify one 
when opening the port, and the other when setting port characteristics with 
lO.XSC. 

The C.CHRL field consists of 2 bytes: 

■ The low byte can contain NX$ETH (1) for Ethernet format or NX$802 
(2) for 802.3 format. 

■ The high byte is reserved. 



RESERVED 



FRAME FORMAT 



C.CHRL 



LKG-1 233-87 



CC.FMO returns the following status codes in the C.STAT field: 

CE.FMI Illegal frame format. 

CE.FMC Frame usage conflict. 
CS.SUC Success. 

CC. SCO (104) = Class I Service for Open 

This characteristic requests 802.3 Class I service for your application. You 
must use CC.SCO to get Class I service; Class II (user-supplied) service is the 
default. 

The C.CHRL field consists of 2 bytes: 

■ The low byte must contain NX$CLI (4). 

■ The high byte is reserved. 



RESERVED 



SERVICE CLASS 



C CHRL 



LKG-1 234-87 
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CC.SCO returns the following characteristics status codes in C.STAT: 

CE.FMC Frame usage conflict. 
CE.SRI Illegal service class. 

CS.SUC Success. 

QIO Completion Status: 

IS .sue The port successfully opened . 

(1) 

1 77736 The LUN you specified is already in use. 

lE.ALN 

(-34.) 

177776 The LUN is not assigned to NX:. 

lE.IFC 

(-2.) 

177646 You specified a non-existent line. 

lE.NSF 

(-26.) 

177760 The port you specified is not available for use by DLX. 

lE.PRI 

(-16.) 

177757 The port you specified is already in use. 

lE.RSU 

(-17.) 



4-24 



DECnet-RSX Programmer's Reference Manual 



lO.XCS 

lO.XSC 

(Set Characteristics) 

4.4.2 lO.XSC — Set Characteristics 

Use: 

Use this QIO to set various port characteristics. The characteristics can include a 
second frame format, multicast addresses, and protocols. 

For a description of the fields in characteristics blocks, refer to Section 4.3.4. 
Always put a zero (0) in the C.DATO field. 

Format: 

QIO$ lO. XSC,lun,[efn],\status\\ast],<pl,p2> 

Arguments: 

lO.XSC 

is the function code whose parameters specify the location and length of the char- 
acteristics buffer. 

lun 

is the logical unit number associated with the port. 
efn 

is an optional event flag number set when the call completes. 
status 

is the address of a 2-word status block that contains completion status. On com- 
pletion, the second word of the I/O status block indicates how much of the char- 
acteristics block was processed. 

ast 

is the entry point into an optional user-written AST routine to execute after this 
QIO completes. 
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pi 

is the address of the characteristics buffer. 
P2 

is the length of the characteristics buffer. The buffer can contain muhiple charac- 
teristics blocks. 

Characteristics Buffer: 

This section has information on the characteristics blocks to use with lO.XSC. 
The blocks are in alphabetical order. 

You can use the following blocks with Ethernet frame format: 

CC.DST Ethernet Protocol Type for Port 
CC . FRM Frame Format for Port 
CC .MCT Multicast Address for Port 

You can use the following blocks with 802.3 frame format: 

CC . FRM Frame Format for Port 
CC .MCT Multicast Address for Port 
CC .GSP Group SAP for Port 

CC .ISP Individual SAP for Port 

CC . SNP SNAP Identifier for Port 

CC . SRV Service Class for Port 

Enter the characteristics blocks in sequential order in the buffer. For example, 
specify the frame format before the characteristics that depend on a particular 
frame format. 

Use the data input size field (CD ATI) to indicate how many bytes of data you are 
supplying. 

Refer to Appendix H for more information on characteristics status codes. 

CC.DST (200) = Protocol Type for Port 

This characteristic contains a protocol type and may include other instruc- 
tions about the use of the protocol type. It can optionally set protocol flags 
and specify Ethernet addresses to which to send and from which to receive 
messages with the protocol type. Unless you set the DF$DIS flag, the charac- 
teristic enables the protocol type. 
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The protocol type must have a value greater than 1 500. Store the low byte of 
the protocol in the high byte of C.CHRL and the high byte of the protocol in 
the low byte of C.CHRL. 

You can use the following protocol flags: 

■ LF$DIS disables the protocol type. 

■ LF$EXC causes the port to receive the protocol type in exclusive mode. 

■ LF$DEF causes the port to receive the protocol type in default mode. 

■ LF$PAD requests padding support for frames with the protocol type. 

You can add the Ethernet addresses of remote nodes to the protocol type 
characteristic, but not with exclusive or default mode. 

The CD ATI field equals 4 + 6 n bytes, where n is the number of addresses 
that you include. 



PROTOCOL I TYPE 



C CHRL 



RESERVED 



PROTOCOL FLAGS 



ADDRESS 1 



ADDRESS n 



n ADDRESSES 
(6 BYTES EACH) 
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CC.DST returns the following characteristics status codes to the C.STAT 
field: 



CE.ACN 


Address usage conflict. 


CE.IUN 


Illegal use of multicast address. 


CE.PCN 


Protocol usage conflict. 


CE.RES 


Resource allocation failure. 


CE.RTL 


Request too large. 


CE.RTS 


Request too small. 


CE.UDF 


Undefined function. 


CS.SUC 


Success. 



CC.FRM (202) = Frame Format for Port 

CC.FRM enables or disables a frame format for the port. Use it to enable a for- 
mat other than the one in which you opened the port. 

The C.CHRL field consists of 2 bytes: 



The low byte specifies the format. The low byte can have the value 
PF$ETH (2) for Ethernet format or PF$802 (4) for 802.3 format. 

The high byte specifies whether to enable or disable the format. A value 
of zero (0) disables the format; any other value enables it. 



ENABLE/DISABLE 



FORMAT 



C CHRL 



LKG-1 235-87 



CC.FRM returns the following characteristics status codes to the C.STAT 
field: 



CE.FMI Illegal frame format. 

CE.FMC Frame usage conflict. 

CE . RES Resource allocation failure . 

CE.RTL Request too large. 

CE.RTS Request too small. 

CE.UDF Undefined function. 

CS.SUC Success. 
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CC.GSP (205) = Group SAP for Port 

This characteristic enables or disables a specified GSAP for the port. You must 
first enable Class I service and an Individual Sap. The C.CHRL field consists of 
two bytes: 

■ The low byte is the GSAP value , in the range to 2 5 5 . , where bit zero (0) 
must equal 1 . 

■ The high byte specifies whether to enable or disable. A value of zero (0) 
disables the GSAP; any other value enables it. 



ENABLE/DISABLE 



GSAP 



CHRL 



LKG-1 237-87 



CC.GSP returns the following characteristics status codes to the C.STAT field: 

CE.FMC Frame usage conflict. 

CE.RES Resource allocation failure. 

CE.RTL Request too large. 

CE.RTS Request too small. 

CE.UDF Undefined function. 

CS.SUC Success. 



CC.ISP(204) = Individual SAP for Port 

This characteristic enables or disables a specified Individual SAP. The 
C.CHRL field consists of two bytes: 

■ The low byte is the SAP value, in the range to 2 5 5 . , where bit must 
equal 0. 

■ The high byte specifies whether to enable or disable. A value of zero (0) 
disables the ISAP; any other value enables it. 



ENABLE/DISABLE 



ISAP 



C CHRL 



LKG-1 238-87 
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CC.ISP returns the following characteristics status codes to the C.STAT field: 



CE.FMC 


Frame usage conflict. 


CE.SPU 


SAP in use. 


CE.RES 


Resource allocation failure. 


CE.RTL 


Request too large. 


CE.RTS 


Request too small. 


CE.UDG 


Undefined function. 


CS.SUC 


Success. 



CC.MCT (201) = Multicast Address for Port 

CC.MCT enables the port to receive messages with the specified multicast 
address. The C.CHRL field consists of 6 bytes. 



1 





3 


2 


5 


4 
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CC.MCT returns the following characteristics status codes in the C.STAT 
field: 



CE.MCE Multicast address already enabled. 

CE . NMA Not a multicast address . 

CE.RES Resource allocation failure. 

CE.RTL Request too large. 

CE.RTS Request too small. 

CE.UDF Undefined function. 

CS.SUC Success. 



CC.SNP(206) = SNAP Identifier for Port 

This characteristic specifies a SNAP identifier and may include other instruc- 
tions about the use of the protocol. It can optionally set protocol flags and 
specify Ethernet addresses to which to send and from which to receive mes- 
sages with the SNAP identifier. Unless you set the LF$DIS flag, the character- 
istic enables the port to send and receive messages that have the protocol. 
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The C.CHRL field consists of the following: 

■ Bytes zero (0) through 4 contain the SNAP identifier. 

■ Byte 5 is reserved. 

■ Byte 6 contains any flags to set (LF$EXC for exclusive mode, LF$DEF for 
default mode, or LF$DIS to disable the SNAP identifier). 

■ Byte 7 is reserved. 

■ Successive 6-byte groups contain any Ethernet addresses to pair with the 
protocol. You cannot add addresses with exclusive or default mode. 

The CD ATI field equals 8 + 6 n bytes, where n is the number of addresses 
that you include. 



PROTOCOL ID (1) 


PROTOCOL ID (0) 


PROTOCOL ID (3) 


PROTOCOL ID (2) 


RESERVED 


PROTOCOL ID (4) 


RESERVED 


PROTOCOL FLAGS 








ADDRESS 1 




ADDRESS n 



n ADDRESSES 
(6 BYTES EACH) 
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CC.SNP returns the following characteristics status codes in the C.STAT field: 

CE . FMC Frame usage conflict . 

CE.RES Resource allocation failure. 

CE.RTL Request too large. 

CE.RTS Request too small. 

CE.SNU SNAP in use. 

CE.UDF Undefined function. 

CS.SUC Success. 

CC.SRV (203) = Service Class for Port 

This characteristic specifies 802.3 Class I service. In the buffer, this character- 
istics block precedes SAP or SNAP identifiers. Use it in conjunction with 
CC.FRM. C.CHRL has two bytes: 

■ The low byte specifies the service class and has the value PF$CLI (10). 

■ The high byte specifies whether to enable or disable. A value of zero (0) 
disables Class I service; any other value enables it. 



ENABLE/DISABLE 



SERVICE CLASS 



C.CHRL 

LKG-1241-87 



CC.SRV returns the following characteristics status codes in the C.STAT field: 

CS.IGN Ignored. 

CE . SRI Illegal service class . 

CE.RES Resource allocation failure. 

CE.RTL Request too large. 

CE.RTS Request too small. 

CE.UDF Undefined function. 

CS.SUC Success. 



4-32 



DECnet-RSX Programmer's Reference Manual 



lO.XGC 



lO.XGC 

(Get Characteristics) 

4.4.3 lO.XGC — Get Characteristics 

Use: 

Use this QIO to return information on various characteristics of a port. The char- 
acteristics to return include the port's frame format, enabled multicast addresses, 
enabled protocols, and so forth. 

For more information on characteristics, refer to section 4.3.4. 



Format: 

QIO$ lO. XGC,lun,[efn]„[status],[astl<pl,p2> 

Arguments: 

lO.XGC 

is the function code whose parameters specify the location and length of a charac- 
teristics buffer that returns port characteristics. 

lun 

is the logical unit number associated with the port. 
efn 

is an optional event flag number set when the QIO completes. 
status 

is the address of a 2 -word status block that contains the QIO completion status. 
On completion, the second word of the I/O status block indicates how much of 
the characteristics block was processed. 

ast 

is the entry point into an optional user-written AST routine to execute after this 
QIO completes. 
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Pi 

is the address of the characteristics buffer. 
P2 

is the length of the characteristics buffer. The buffer can contain multiple charac- 
teristics blocks. 

Characteristics Buffer: 

This section has information on the characteristics blocks to use with lO.XGC. 
The blocks are arranged alphabetically. 

You can use the following blocks with Ethernet frame format: 

CC .DST Ethernet Protocol Type for Port 
CC . FRM Frame Format for Port 
CC . MCT Multicast Address for Port 

You can use the following blocks with 802.3 frame format: 

CC . FRM Frame Format for Port 

CC.GSP Group SAP for Port 

CC . ISP Individual SAP for Port 

CC .MCT Multicast Address for Port 
CC . SNP SNAP Identifier for Port 

CC . SRV Class I Service for Port 

For characteristics with multiple occurrences, append multiple blocks. Each sub- 
sequent block returns the next occurrence of the characteristic. For example, 
CC.MCT returns an enabled multicast address; for multiple multicast addresses, 
append multiple CC.MCT blocks in the buffer. If no more occurrences of the char- 
acteristic exist, the C.STAT field returns an lE.IGN (ignored) error. 

For variable-length fields, such as a protocol that may or may not be paired with a 
number of addresses, check the contents of the C.DATO field for the size of the 
returned data. 

Refer to Appendix H for more information on characteristics status codes. 
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CC.DST(200) = Ethernet Protocol Type for Port 

This characteristic returns information on the enabled Ethernet protocol 
type, including the protocol flags and any Ethernet addresses you may have 
paired with the protocol. A recurrence of the characteristics block returns 
information on the next enabled protocol type. 

The protocol type and flags consist of 2 bytes each, and each address consists 
of 6 bytes. The high byte of C.CHRL returns the low byte of the protocol and 
the low byte of C.CHRL returns the high byte of the protocol. 



PROTOCOL i TYPE 



C.CHRL 



PROTOCOL I FLAGS 
I 



ADDRESS 1 



ADDRESS n 



n ADDRESSES 
(6 BYTES EACH) 



LKG-1 242-87 



The value in the C.DATO field equals 4 + 6n bytes, where n is the number of 
addresses for the protocol type. 
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CC.DST returns the following characteristics status codes in the C.STAT 
field: 

CE . D AO Data overrun . 
CE.RTS Request too small. 

CS.SUC Success. 

CC.FRM(202) = Frame Format for Port 

This characteristic returns the current frame format(s) for the port. 

The C.CHRL field consists of 2 bytes: 

■ The low byte returns PF$ETH (2) for Ethernet format, PF$802 (4) for 
802.3 format, or PF$ETH!PF$802 (6) for both formats. 

■ The high byte is reserved. 



RESERVED 



FORMAT 



C.CHRL 



LKG- 1243-87 



CC.FRM returns the following characteristics status codes in the C.STAT 
field: 

CE.RTL Request too large. 

CE.RTS Request too small. 

CS.SUC Success. 

CC.MCT(201) = Multicast Address for Port 

This characteristic returns a multicast Ethernet address currently enabled for 
the port. A recurrence of the characteristics block returns the next enabled 
multicast address. 

The C. CHRL field consists of 6 bytes. For more information on Ethernet 
addresses, refer to section 4.3.3- 
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C.CHRL 



■ MULTICAST 

I 

- ADDRESS 



LKG-1 244-87 



CC.MCT returns the following characteristics status codes in the C.STAT 
field: 



CE . RTL Request too large . 

CE.RTS Request too small. 

CS.SUC Success. 



CC.GSP(205) = Group SAP for Port 

This characteristic returns information on enabled Group SAPs. The C.CHRL 
field has two bytes: 

■ The high byte returns the number of currently-enabled Group SAPs for 
the port. 

■ The low byte returns the first enabled Group SAP for the first occur- 
rence of the block. The next occurrence of the block returns the next 
enabled Group SAP. 



GSAP 



C.CHRL 



LKG-1 245-87 



TOTAL GSAPs 



CC.GSP returns the following characteristics status codes in C.STAT: 

CE . FMC Frame usage conflict . 

CE.RTL Request too large. 

CE.RTS Request too small. 

CS.IGN Ignored. 

CS.SUC Success. 
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CC.ISP (204) = Individual SAP for Port 

This characteristic returns an enabled Individual SAP. A recurrence of the 
characteristics block returns the next Individual SAP. 

The C.CHRL field consists of two bytes: 

■ The low byte is the SAP, which is in the range zero (0) to 255 , where bit 
zero (0) equals 0. 

■ The high byte returns the number of currently-enabled Individual SAPs 
for the port. 



TOTAL ISAPs 



ISAP 



C.CHRL 

LKG- 1246-87 



CC.ISP returns the following characteristics status codes in the C.STAT field: 

CE.FMC Frame usage conflict. 

CE.RTL Request too large. 

CE.RTS Request too small. 

CS.SUC Success. 



CC.SNP(206) = SNAP Identifier for Port 

This characteristic returns information about the SNAP identifiers currently 
enabled for the port. The first occurrence of the block returns information on 
the first SNAP; subsequent occurrences of the block each return the next 
SNAP. 



The C.CHRL field consists of 8 bytes: 

■ Bytes 0-4 contain the SNAP identifier. 



■ Byte 5 returns the number of currently-enabled SNAP identifiers for the 
port. 

■ Byte 6 contains any protocol flags. 

■ Byte 7 returns the number of ports currently using this SNAP identifier. 
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■ Successive 6-byte groups contain any Ethernet addresses associated with 
the protocol. 



PROTOCOL ID (1) 


PROTOCOL ID (0) 


PROTOCOL ID (3) 


PROTOCOL ID (2) 


TOTAL SNAPS 


PROTOCOL ID (4) 


TOTAL PORTS 


PROTOCOL FLAGS 



ADDRESS 1 



ADDRESS n 



n ADDRESSES 
(6 BYTES EACH) 



LKG-1 247-87 



CC.SNP returns the following characteristics status codes in the C.STAT field: 

CE . EMU Erame usage conflict . 

CE.RTL Request too large. 

CE.RTS Request too small. 

CS.SUC Success. 
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CC.SRV (203) = Class I Service for Port 

This characteristic returns the value for 802.3 Class I service when 802.3 is a 
second frame format. Use it in conjunction with CC.FMM. 

The C.CHRL field has two bytes: 

■ The low byte returns PF $ CLI ( 1 0) if Class I service is enabled . 

■ The high byte is reserved. 



RESERVED 



SERVICE CLASS 



C.CHRL 

LKG- 1248-87 



CC.SRV returns the following characteristics status codes in the C.STAT field: 

CE.RTL Request too large. 

CE.RTS Request too small. 

CS.SUC Success. 
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lO.XTM 

(Transmit a Message on the Port) 

4.4.4 lO.XTM — Transmit a Message on the Port 

Issue this QIO to transmit a message on an open port. In entering the QIO, you 
specify the address and length of a buffer that contains the data that you want to 
transmit. When the QIO executes, it transfers that data to a network buffer. 

You can set a number of characteristics for the transmit operation, including the 
destination address, frame format, protocol, and so forth. 

Format: 

QIO$ l0.xrM,lun,[efn]„[status],[ast],<pl,p2,\p3,p4] > 

Arguments: 

lO.XTM 

is the function code for transmitting a message. 
lun 

is the logical unit number associated with the port. 
efn 

is an optional event flag number set when the call completes. 
status 

is the address of a 2-word status block that contains completion status. The status 
block contains the QIO completion status in the low-order byte of the first word 
(see under "QIO Completion Status"). 

ast 

is the entry point into an optional user-written AST routine to execute after the 
QIO completes. 

is the address of the user buffer that contains the message to transmit. 
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P2 

is the length of the message to transmit. 
P3 

is the address of the characteristics buffer. 
p4 

is the length of the characteristics buffer. 

Characteristics Buffer: 

This section has information on the characteristics blocks to use with lO.XTM. 
The blocks are described in alphabetical order. 

You can use the following characteristics with Ethernet frame format: 

CC.ADR Address for Message 

CC . FMM Frame Format for Message 

CC.PRO Ethernet Protocol Type for Message 

You can use the following characteristics with 802.3 frame format: 

CC.ADR Address for Message 

CC.CTM Control Field for Message 

CC. FMM Frame Format for Message 

CC. SNM SNAP Identifier for Message 

CC. SPM Destination and Source SAP for Message 

Enter the characteristics blocks into the buffer in sequential order. For example, 
specify the frame format before the characteristics that depend on a particular 
frame format. 

Refer to Appendix H for more information on characteristics status codes. 

CC.ADR (100) = Address for Message 

This characteristic specifies the Ethernet address to use as a destination for 
transmission; it is required on each transmission. The address consists of 6 
bytes. For information on setting up the Ethernet address for DECnet nodes, 
refer to the introductory sections of this chapter. 
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DESTINATION- 
I 

ADDRESS - 



C.CHRL 



LKG- 1249-87 



CC.ADR returns the following characteristics status codes in the C.STAT 
field: 

CS.IGN Ignored. 
CS.SUC Success. 

CC.CTM (107) = Control Field for Message 

This characteristic specifies the value for the 802.3 control (CTL) field. Use 
CC.CTM in conjunction with an Individual or Group SAP (ISAP or GSAP) 
address to specify the contents of the frame. 

For user-supplied service, you can create symbolics to use in the control field 
in accordance with the IEEE standard. For Class I service, you can lEse the fol- 
lowing symbolics: 

Symbolic Message Type 

$CSUIF UI 
$CSXIF XID 
$CSTSF TEST 



CTL(1; 



CTL (0) 



C CHRL 

LKG-1 250-87 
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CC.CTM returns the following characteristics status codes in the C.STAT 
field: 



CS.IGN 
CS.SUC 



Ignored. 
Success. 



CC.FMM(105) = Frame Format for Message 

This characteristic specifies the frame format for the message. The character- 
istic block is necessary only with 802.3 transmissions, since Ethernet is the 
default format. The C.CHRL field consists of 2 bytes: 

■ The low byte contains NX$ETH (1) for Ethernet format or NX$802 (2) 
for 802. 3 format. 

■ The high byte is reserved. 



RESERVED 



FRAME FORMAT 



C CHRL 



LKG-1251-87 



CC.FMM returns the following characteristics status codes in the C.STAT 
field: 



CS.IGN 
CS.SUC 



Ignored. 
Success. 



CC . PRO (101) = Protocol Type for Message 

This characteristic supplies the message's protocol type. You must supply the 
protocol type on all Ethernet-format transmissions. 

The C.CHRL field contains 2 bytes for the protocol type. 



PROTOCOL 1 TYPE 



C.CHRL 

LKG-1 252-87 



CC.PRO returns the following characteristics status codes in the C.STAT 
field: 



CS.IGN 
CS.SUC 



Ignored. 
Success. 
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CC.SNM (110) = SNAP Identifier for Message 

This characteristic specifies a message's SNAP identifier. Use six bytes, with 5 
bytes for the SNAP and 1 byte reserved, as follows: 



SNAP (1) 


SNAP (0) 


SNAP (3) 


SNAP (2) 


RESERVED 


SNAP (4) 



LKG-1 254-87 



CC.SNM returns the following characteristics status codes in the C.STAT 
field: 

CS.IGN Ignored. 
CS.SUC Success. 

CC.SPM(106) = Destination and Source SAPs for Message 

This characteristic specifies a message's Destination and Source SAPs. Use it 
in conjunction with CC.CTM. 



SSAP 



DSAP 



C.CHRL 



LKG-1 253-87 



CC.SPM returns the following characteristics status codes in the C.STAT 
field: 

CS.IGN Ignored. 
CS.SUC Success. 
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QIO Completion Status: 

IS. sue The message was successfully transmitted to the remote node. 
(1) 

Xllld 1 The transmission was aborted. Close and reopen the port. 

lE.ABO 

(-15.) 

mill You get this code with Ethernet frame format if you omit the 

IE. BAD protocol type and/or remote address. You get the code with 

(-1) 802 . 3 frame format if you omit either a SNAP identifier or a 
DSAP/SSAP pair and control field. 

177776 The LUN is not assigned to NX: . 

lE.IFC 

(-2.) 

177733 No open port has the specified LUN . 

lE.NLN 

(-37.) 

177772 The transmit buffer is too large. This status code applies only to 

lE.SPC PDP-1 1/44 or PDP-1 1/70 with extended memory. 

(-6.) 
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lO.XRC 

lO.XRC 

(Receive a Message on the Port) 

4.4.5 lO.XRC — Receive a Message on the Port 

Issue this QIO to receive a message from a remote node. 

Format: 

QIO$ lO. XRC,lun,[efn]„[status],[ast],<pl,p2,\p3,p4]> 

Arguments: 

lO.XRC 

is the function code for receiving a message. 
lun 

is the logical unit number associated with the port. 
efn 

is an optional event flag number set when the call completes. 
status 

is the address of a 2-word status block. The status block contains the QIO comple- 
tion status in the low-order byte of the first word (see under "QIO Completion 
Status"). 

ast 

is the entry point into an optional user- written AST routine to execute after this 
QIO completes. 

Pl 

is the address of a user buffer to receive the message. 
P2 

is the length, in bytes, of the user buffer to receive the message. The length of the 
received message cannot exceed the system buffer, regardless of the length you 
specify in p2. 
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iO.XRC 



P3 

is the address of the characteristics buffer. 
p4 

is the length of the characteristics buffer. 

Characteristics Buffer: 

This section has information on the characteristics blocks to use with IO.XRC. 
The blocks are in alphabetical order. 

You can use the following characteristics with Ethernet frame format: 

CC .ADR Source Address of Message 

CC . DAD Destination Address of Message 

CC . FMM Frame Format of Message 

CC . PRO Ethernet Protocol Type of Message 

You can use the following characteristics with 802.3 frame format: 

CC .ADR Source Address of Message 

CC.CTM Control Field of Message 

CC . DAD Destination Address of Message 

CC.FMM Frame Format of Message 

CC.SNM SNAP Identifier of Message 

CC . SPM Destination and Source S APs of Message 

Refer to Appendix H for more information on characteristics status codes. 
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lO.XRC 



CC.ADR(IOO) = Address of Message 

This characteristic returns the source Ethernet address from which a received 
frame was sent. The address consists of 6 bytes. 



SOURCE ■ 

I 

ADDRESS' 



C.CHRL 



LKG-1 255-87 



CC.ADR returns the following characteristics status codes in the C.STAT 
field: 



CS.IGN 
CS.SUC 



Ignored. 
Success. 



CC.CTM (107) = Control Field of Message 

This characteristic returns the 802.3 control (CTL) field's value. The control 
field tells what type of data the frame contains in frames with DSAP/SSAP 
identifiers. 

In frames with Class I service only, the control field value will be one of the 



following: 




Symbolic 


Message Type 


$CSUIF 


UI 


SCSXIF 


XID 


$CSTSF 


TEST 



CTL(i; 



CTL (0) 



C.CHRL 



LKG-1 256-87 
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lO.XRC 



CC.CTM returns the following characteristics status codes in the C.STAT 
field: 

CS.IGN Ignored. 
CS.SUC Success. 

CC. DAD (102) = Destination Address of Message 

This characteristic returns the destination address on a received frame; it will 
be either your physical address or one of your enabled multicast addresses. 
The destination address consists of 6 bytes. 



DESTINATION 

I 

ADDRESS 



C.CHRL 



LKG-1 257-87 



CCD AD returns the following characteristics status codes in the C.STAT 
field: 

CS.IGN Ignored. 
CS.SUC Success. 

CC.FMM(105) = Frame Format of Message 

This characteristic returns the frame format of a received message. The 
C.CHRL field consists of 2 bytes: 

■ The low byte returns NXSETH (1) for Ethernet format or NX$802 (2) for 
802.3 format. 

■ The high byte is reserved. 



RESERVED 



FRAME FORMAT 



C.CHRL 

LKG-1 258-87 
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lO.XRC 



CC.FMM returns the following characteristics status codes in the C.STAT 
field: 



CS.IGN 
CS.SUC 



Ignored. 
Success. 



CC. PRO (101) = Protocol Type of Message 

CC.PRO returns the protocol type for an Ethernet-format frame. The 
C.CHRL field contains 2 bytes for the protocol type. 



PROTOCOL I TYPE 



C.CHRL 

LKG-1 252-87 



CC.PRO returns the following characteristics status codes in the C.STAT 
field: 



CS.IGN 
CS.SUC 



Ignored. 
Success. 



CC.SNM(llO) = SNAP Identifier of Message 

This characteristic returns the SNAP identifier of a received message. The 
SNAP identifier has 5 bytes, formatted as follows: 



SNAP (1) 


SNAP (0) 


SNAP (3) 


SNAP (2) 


RESERVED 


SNAP (4) 



C.CHRL 



LKG-1 259-87 



CC.SNM returns the following characteristics status codes in the C.STAT 
field: 



CS.IGN 
CS.SUC 



Ignored. 
Success. 
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CC.SPM(106) = SAPs of Message 

CC.SPM returns the Destination SAP (DSAP) and Source SAP (SSAP) address of 
a received message. The C.CHRL field has two bytes: the low byte stores the 
DSAP, and the high byte stores the SSAP. 



SSAP 



DSAP 



C.CHRL 

LKG-1 260-87 



CC.SPM returns the following characteristics status codes in the C.STAT 
field: 

CS.IGN Ignored. 
CS.SUC Success. 



QIO Completion Status: 

IS. sue You successfully received a message from the remote node. The 

(1) second word of the I/O status block contains the number of 
bytes you received. 

177761 The receive function was aborted because an unrecoverable 

IE. ABO error occurred in the hardware device. Close and reopen the 

(-15.) port. 

177763 Some data was lost because a message arrived before the appli- 

lE.DAO cation issued an lO.XRC directive, or because the user buffer 

(-13 .) was too small and truncated the message . The user buffer length 
is in the second word of the I/O status block. 

177776 The LUN is not assigned to NX: . 

IE. IPC 

(-2.) 

177733 No open port has the specified logical unit number. 

lE.NLN 

(-37.) 

17764 1 A timeout condition occurred. The timer interval that you spec- 
IE. TMO if led in opening the port expired without a message arriving. 
(-95.) 
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lO.XCL 

lO.XCL 
(Close the Port) 

4.4.6 lO.XCL ^ Close the Port 

Use: 

Issue lO.XCL to close the port. 
Format: 

QIO $ lO .XCL , /mm , [efn] , , [status] , [ast] 
Arguments: 

lO.XCL 

is the function code that closes the port. 
lun 

is the logical unit number associated with the port. 
efn 

is an optional event flag number set when the call completes. 
status 

is the address of a 2-word status block. The status block contains the QIO comple- 
tion status in the low-order byte of the first word (see under "QIO Completion 
Status"). 

ast 

is the entry point into an optional user-written AST routine to execute after this 
QIO completes. 
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QIO Completion Status: 

IS . sue The port has successfully closed. 

(1) 

177116 The LUN is not assigned to NX: . 

lE.IFC 

(-2.) 

V711'55 No open port has the specified LUN . 

lE.NLN 

(-37.) 
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4.4.7 DLX QIO Programming Examples 

The following programs are examples of programming DLX for an Ethernet. The 
first example uses 802.3 frame format. The second example uses Ethernet frame 
format. 
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4.7.1 802.3 Example 



This program is a DLX 802.3 test program. You can run the program on two 
nodes to test the nodes' ability to send and receive 802.3 frames on the data link 
level. On the transmitting node, the task builds and sends 802.3 XID, TEST, or UI 
frames. On the receiving node, the task simply returns the received frames to the 
sender. 

.TITLE 802TST - 802.3 Test Tool 
.IDENT /vol. 00/ 

Copyright (C) 1983, 1985, 1986, 1987 by 
Digital Equipment Corporation, Maynard, Mass. 

This software is furnished under a license and may be used and copied 
only in accordance with the terms of such license and with the 
inclusion of the above copyright notice. This software or any other 
copies thereof may not be provided or otherwise made available to any 
other person. No title to and ownership of the software is hereby 
transferred. 



The information in this software is 
and should not be construed as 
Corporation. 



subject to change without notice 
a commitment by Digital Equipment 



Digital assumes no responsibility for the use or reliability of its 
software on equipment which is not supplied by Digital. 



This program tests an 802.2 data link. As a "sender," the 
task builds an 802.3 XID, TEST, or UI command frame and transmits it 
to the remote responder. As a "receiver," the task transmits the 
received frames back to the sender. The sending task then logs the 
returned data to the terminal or to a file. 

The program is initiated by command line options: 

Option Default Comment 



/DEV[ ICE]=ddd-n 

/DSA[P]=n 

/GSA[P]=n 

/HAR[DWARE]=nn-. . .- 

/ISA[P]=n 

/LOG 

/MES[ SAGE ] =message 

/NOD[E]=n.m 

/PHY[SICAL]=nn-. . .- 

/RES [PONDER] 

/SIZ[E]=n 

/USE[R] 

/SNA[P]=nn-. . .-nn 



/DEVICE=UNA-0 Controller to use 

/DSAP=4 Destination SAP 

none Group SAP 

none Remote hardware address 

/ISAP=4 Individual SAP 

none Log to 802TST.DAT 

/MES=XID Build XID, TEST or UI 

none Remote DECnet address 

none Remote physical address 

none Responder mode 

60. Size to transmit 

none User-supplied service 

none SNAP protocol identifier 



The following conimands configure 802TST to respond to frames sent eithe 
to SAP 8 or to SNAP protocol identifier 01-02-03-04-05. The frames wil 
come from the controller QNA-0 on node 55.202: 



>INS 802TST 

>802 /DEV=QNA-0/RES/ I SAP=8/SNAP=0 1-02-0 3-04-0 5 
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The program loops back received 802.3 frames until it is aborted. 

The following commands are executed on a different system on the same LAN. 
They cause 802TST to send a 60. byte TEST message to the above image of 
802TST on node 55.202. They also cause the program to log the response to 
the file SY: [currentj802TST.DAT: 



>INS 802TST 

>8 2 /DEV=QNA- / 1 SAP= 1 6/DS AP= 8 /NOD= 55.202 /MES=TEST/LOG 

The program exits after receiving and logging the response. Note that 

the responder program must be started *before* the sender program transmits 

any frames. 

To assemble, use the following command string: 

MAC 802TST,802TST/-SP/LI :TTM =IN: [ 130 , 10 ]NETLIB/ML, [ 200 , 200 ] 802TST 



To task build, use the following command string: 



802TST/PR:0, 802TST/-SP = 
802TST 

[101,124]NETLIB/LB 
/ 

UNITS=4 

ASG=TI : 1:2:3:4 
TASK=. . .802 
GBLDEF=$HELP:0 
// 



Note: the IN: device must be the DECnet distribution device 
after the PREGEN {if> any) has been performed. 



.SBTTL Macros 



.MCALL DIR$ , ALUN$S , QIOW$ , QIO$ ,CLEF$S , SETF$S , WTSE$S , EXIT$S , EXST$S 

.MCALL GTIM$S , SREX$S , ENAR$S , DSAR$S , ASTX$S 

.MCALL GCMLB$ ,GCML$ , ISTAT$ , STATE? , TRAN$ 

.MCALL FCSMC$ 

.MCALL DLXDF$ ,CHRDF$ ,CSMDF$ 



FCSMCS 
DLXDF$ 
CHRDF$ 
CSMDF$ 



, , , ETHERNET 



Define FCS macros 
Define DLX and EPM symbols 
Define characteristics 
Define CSMA/CD symbols 



.MACRO 
. IRP 
MOV 
.ENDM 
.ENDM 



SAVRG list 
reg , <1 ist> 
reg,-(SP) 

SAVRG 



.MACRO RESRG list 
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.IRP reg,<list> 

MOV (SP)+,reg 
.ENDM 

.ENDM RESRG 



.MACRO TYPE adr,len,vfc 

MOV adr,OUTQIO+Q. lOPL 

MOV len,OUTQIO+Q. IOPL+2 
.IF NB,vfc 

MOV vfc,0UTQI0+Q.I0PL+4 
.IFF 

MOV #40,OUTQIO+Q. IOPL+4 
.ENDC 

DIR$ #OUTQIO 

.ENDM TYPE 



A: 
B: 



.MACRO LOG adr,len,?A,?B 

BIT #OP.LOG,OPTFLG 

BNE A 

TYPE adr,len 

BR B 

PUT$ #LOGFIL,adr,len 

. ENDM LOG 



.MACRO FORMAT adr , f mt 

MOV adr,R2 

MOV f mt , Rl 

MOV #FMTBUF,RO 

CALL $EDMSG 

MOV Rl , FMTL 

. ENDM FORMAT 



.MACRO ERROR adr,fnit 

FORMAT <adr>,<fmt> 

LOG #FMTBUF,FMTL 

. ENDM ERROR 



.MACRO 

.WORD 

.WORD 

.WORD 

.ENDM 



CHRGEN 
code 
size 
0,0 

CHRGEN 



code , size 



Characteristic type = code 
Buffersize = size bytes 
Reserved, status 



.MACRO OFFSET block , symbol 

.IIF EQ,<BF-1> - symbol = .-block' 1 

.ENDM OFFSET 



.SBTTL Local constants 



EQUALS = '= 

SPACE =40 

TAB = 11 

CMDLUN = 1 
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TILUN = 2 

CHNLUN = 3 

LOGLUN = 4 

CMDEFN = 1 

TIEFN = 2 

CHNEFN = 3 

DONE = 4 



I SAP 

DSAP 

AREABT 

MXAREA 

MXNODE 

MXCTL 

XIDl 

XID2 

XID3 

MAXFRM 

BUFSIZ 

NUMBUF 

TMO 



= 4 
= 

= 176000 
= 63. 
= 1023. 
= 377 

= -^BlOOOOOOl 
= -"BOGOOOOOl 
= '^BOOOOOOOO 
= 1492. 
= MAXFRM 
= 4, 
= 5 



Default Individual/Source SAP 
Default Destination SAP 
Area mask 
Area limit 
Node limit 

Maximum control value 
XID message bytes 



Maximum frame data 
Receive buffer length 
Number of receive buffers 
Time-out value in seconds 



.SBTTL 
OPTFLG: .BLKW 



.SBTTL Impure data 
.PSECT $ I DATA D,RW 

.TPARS 

1 



action routine state variables 
Option flags 



OP . DEV 




1 


/DEV[ ICE] 


OP . DSP 




2 


/DSA[P] 


OP.GSP 




4 


/GSA[P] 


OP . HDW 




10 


/HAR[DWARE ADDRESS] 


OP. ISP 




20 


/ISA[P] 


OP . LOG 




40 


/LOG 


OP . MSG 




100 


/MESCSAGE TYPE] 


OP . NOD 




200 


/NOD[E] 


OP . PHY 




400 


/PHY[SICAL ADDRESS] 


OP.RSP 




1000 


/RES [PONDER] 


OP.SIZ 




2000 


/SIZ[e] 


OP.USR 




4000 


/USE[R] 


OP.SNP 




10000 


/SNA[P] 


5GFLG: 


BLKW 1 


Message type flags 


OP.TST 




1 


TEST 


OP.UIF 




2 


UI 


OP.XID 




4 


XID 



MSADR: 


.BLKW 


1 


Message address 


MSLEN: 


.BLKW 


1 


length 


NDADR : 






Remote node address (48 bits) 


HWADR : 






Hardware address 


PHADR: 


.BLKW 


3 


Physical address 


CTL: 


.BLKW 


1 


CTL field 


SIZE: 


.BLKW 


1 


Size of data block to transmit 


DEVNM: 


.BLKW 


2 


Device length, address 


NODID: 


.BLKW 


2 


Node address (area, node) 


HXADR : 


.BLKW 


3 


Hex address 


GSAP: 


.BLKB 


1 


Group SAP 
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. ISAP: 


.BLKB 


1 


; Individual SAP 


. DSAP : 


.BLKB 


1 


; Destination SAP 


. SNAP ; 


.BLKB 


5 


; SNAP protocol identifier 


.HXDIG: 


.BLKB 


1 


; Hex digit 


. HXBYT : 


.BLKB 
.EVEN 


1 


; Hex byte 





.SBTTL 


OUTQIO 


QIOW$ 


OPNQIO 


QIOW$ 


SETQIO 


QIOW$ 


RCVQIO 


QIO$ 


XMTQIO 


QIOW$ 


CLSQIO 


QIOW$ 




.SBTTL 


LOGFIL: FDBDF$ 




FDAT$A 




FDRC$A 




FDOP$A 




FSRSZ$ 




.SBTTL 



Open 
OPNCHB; 



Directive parameter blocks 
IO.WVB,TILUN,TIEFN, , , ,<0,0,40> 

IO.XOP,CHNLUN,CHNEFN, ,CHNSB, , <0 , , , OPNCHB , 0> 
IO.XSC,CHNLUN,CHNEFN, ,CHNSB, ,<0,0> 
IO.XRC,CHNLUN, , , , RCVAST , <0 , BUFSIZ , , RC . LEN> 
IO.XTM,CHNLUN,CHNEFN, ,CHNSB, ,<0,0,0,0> 
I . XCL , CHNLUN , CHNEFN 

Log file structures 

R.VAR,FD.CR 
,FMTBUF, 132. 
LOGLUN, , LOGDFN 

2 ; Allocate space for 2 files 

Channel characteristics buffers 
characteristics buffer 



Define frame format (=802.3) 



OPNCLO = 



CHRGEN CC . FMO , 2 
.WORD NX$802 
- OPNCHB 



Define service class (Class I) 



OPNCHL = 



CHRGEN CC.SC0,2 
.WORD NX$CLI 
- OPNCHB 



Frame format is 802.3 
Length for user service 



; Service class is Class I 
; Length for Class I service 



; Set characteristics buffers 
SETBFl: 

; Define Individual SAP 

; Individual SAP 
; Enable flag (0=disable) 

SETBFl: 



CHRGEN CC.ISP,2 
SET ISP: .BLKB 1 

.BYTE 1 
SETLNl = .-SETBFl 

; Define Group SAP 
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CHRGEN CC.GSP,2 
SETGSP: .BLKB 1 ; Group SAP 

.BYTE 1 ; Enable flag 

SETLN2 = .-SETBF2 

Define SNAP protocol identifier 

SETBF3: 

CHRGEN CC.SNP,8. 
SETSNA: .BLKB 5 

.BLKB 1 

.BYTE LF$EXC 

.BLKB 1 
SETLN3 = .-SETBF3 



SNAP protocol identifier 
RESERVED 
Exclusive use 
RESERVED 



.SBTTL . Message characteristics buffers 

r 

; Transmit characteristics buffer 
XMTBFR: 

; Define Ethernet address 

CHRGEN CC.ADR,6 
XMTADR: .BLKW 3 ; Ethernet address 

Define frame format (=802.3) 

CHRGEN CC.FMM,2 

.WORD NX$802 ; 802.3 frame format 

Define Destination SAP and Source SAP 

CHRGEN CC.SPM,2 
XMTDSP: .BLKB 1 ; Destination SAP 

XMTSSP: .BLKB 1 ; Source SAP 

Define PDU type 

CHRGEN CC.CTM,2 
XMTCTL: .WORD ; 80 2.3 message type 

XMTLNl = .-XMTBFR 

Define SNAP protocol identifier 

CHRGEN CC.SNM,6 
XMTSNA: .BLKW 3 
XMTLN2 = .-XMTBFR 

.SBTTL Ring buffers 

BF =0 
. REPT NUMBUF 
BF = BF+1 

.IRP N,<\BF> 

(continued on next page) 
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Buffer descriptor block #'n 
.PSECT $IBDB D,RW 

BDB'n: 

; I/O status block 
OFFSET BDB,BD.STS 
.BLKW 2 

; Link to next BDB in ring 
OFFSET BDB,BD.LNK 
•IF LT,<BF-NUMBUF> 
.IRP NEXT,<\BF+1> 
.WORD BDB 'NEXT 
.ENDM 
. IFF 

.WORD BDBl 
.ENDC 

; Data buffer address 

OFFSET BDB,BD.BUF 
.WORD BUF'N 

; Received chr buffer address 
OFFSET BDB,BD.RCH 
.WORD RCH'N 

; Transmitted chr buffer address 
OFFSET BDB,BD.XCH 
.WORD XCH'N 

; Buffer Descriptor Block length 
OFFSET BDB,BD.LEN 



Data buffer #'n 

.PSECT $IBUF D,RW 

BUF • n : 

.BLKB BUFSIZ 
.EVEN 

Received characteristics buffer #'n 
.PSECT $IRCH D,RW 

RCH ' n : 

; Destination Ethernet address 

CHRGEN CC.DAD,6 
OFFSET RCH, RC. DAD 
.BLKW 3 

; Source Ethernet address 

CHRGEN CC.ADR,6 
OFFSET RCH, RC. SAD 
.BLKW 3 

; SNAP protocol identifier 

CHRGEN CC.SNM,6 
OFFSET RCH,RC.SNM 
. BLKW 3 

; Destination and source SAPs 



4-62 



DECnet-RSX Programmer's Reference Manual 





CHRGEN 


CC.SPM,2 






OFFSET 


RCH,RC.SPM 






.BLKW 


1 








; Control field 






CHRGEN 


CC.CTM,2 






OFFSET 


RCH,RC,CTM 






.BLKW 


1 








; Received chr buffer length 




OFFSET 


RCH , RC . LEN 




; Transmitted characteristics buffer #'n 








$IXCH D,RW 




YPH ' n • 
^\^n J 1 • 












; Frame format (J 


302.3) 






CC . FMM , 2 - 






.WORD 


NX$802 








; Destination Ethernet address 






CC . ADR , 6 






OFFSET 


XCH,XC.ADR 






.BLKW 


3 








; Destination and Source SAPs 




ii r\ o i-j iN 


CC . SPM , 2 








XCH,XC.SPM 






BLKW 


1 








; Control field 






CHRGEN 


CC . CTM , 2 






yjc r oCj i 


XCH , XC . CTM 






BLKW 


1 








; Transmit chr buffer length (DSAP/SSAP/CTL) 




Kjc r oiii i 


XCH,XC.LN1 








; SNAP protocol identifier 






CC.SNM, 6 






vjr r ollj i 


XCH,XC.SNM 






.BLKW 


3 








; Transmit chr buffer length (SNAP protocol) 




OFFSET 


XCH,XC.LN2 






.ENDM 








.ENDR 








. SBTTL 


Miscellaneous local storage 


CMDBUF : 


.BLKB 


134. 


Command buffer 


NUMRCV: 


.BLKW 


1 


Number of received frames 


EXSTAT : 


.BLKW 


1 


Exit status 


FMTDAT : 


.BLKW 


25. 


Data buffer for formatting 


RCVSB : 


.BLKW 


2 


Receive status 


CHNSB : 


.BLKW 


2 


Channel status 


lOSB: 


.BLKW 


1 


Address of receive status block 


FMTL: 


.BLKW 


1 


Length of formatted record 


TIMBUF: 


.BLKW 


8. 


Time buffer 


TIMOUT: 


.BLKW 


1 


Time-out for receives 


FMTBUF: 


.BLKW 


300. 
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■SBTTL 
.PSECT 



Pure data 
$PDATA D,RO 



ERRFMl i 

ERRFM2 ; 

NSFFMT: 

ASNFMl i 

ASNFM2 i 

ASNFM3 ; 

OPNFMT: 

SETFMT: 

RCVFMT; 

XMTFMT; 

DEVDFB: 

DEVDFL 

GCLERR: 

PRSERR: 



TIMFMT: 
OPNCHF; 



SETCHF: 



XMTCHF; 



RCVMS 1 ; 
RCVLNl 
RCVMS 2 ; 
RCVLN2 
RCVMS 3 ; 
RCVLN3 
RCVMS 4 ; 
RCVLN4 
RCVMS 5; 



.SBTTL 
.NLIST 
.ASCIZ 
.ASCIZ 
.ASCIZ 
.ASCIZ 
.ASCIZ 
.ASCIZ 
•ASCIZ 
.ASCIZ 
.ASCIZ 
.ASCIZ 
.ASCII 



Text strings 



BEX 



CTL %D.\ 



\%N802 — %I, $DSW is %D.\ 
\%N802 — %I, I/O status is %P %P\ 
\No such file\ 

\Cannot assign LUN to channelX 
\Cannot assign LUN to command terminalX 
\Cannot assign LUN to output terminalX 
XCannot open lineX 
XError defining ISAPX 
XReceive errorX 
XTransmit errorX 
XUNA-OX 
=. -DEVDFB 

.ASCIZ X%NGet command line error, code = %PX 

.ASCII X%NSyntax error: "%VA"X 

.ASCII X%N%4S0PTFLG %P MSGFLG %PX 

.ASCII X%N%4S.DEVNM "%VA" .NDADR %P %P %PX 

.ASCII X%N%4S.ISAP %D. .GSAP %D. . DSAP %D. 

.ASCIZ X%N%4S.SNAP %5BX 

.ASCIZ /%N%Y %3Z/ 

.ASCII X%NOpen characteristicsiX 
.ASCII X%NCC.FMO (=%P) %P %P %P %PX 
.ASCIZ X%NCC.SCO (=%P) %P %P %P %PX 

.ASCII X%NSet characteristics^ 

.ASCII X%NCC.ISP (=%P) %P %P %P %PX 

.ASCII X%NCC.GSP {=%P) %P %P %P %P\ 

.ASCIZ X%NCC,SNP (=%P) %P %P %P %P %P %PX 

.NLIST BEX 

.ASCII X%NTransmit characteristicsrX 

.ASCII X%NCC,ADR (=%P) %P %P %P %P %P %PX 

.ASCII X%NCC.FMM (=%P) %P %P %P %PX 

.ASCII X%NCC.SPM (=%P) %P %P %P %PX 

.ASCII X%NCC.CTM (=%P) %P %P %P %P\ 

.ASCIZ X%NCC.SNM (=%P) %P %P %P %P %P %PX 



.ASCII <12><15>/Dest inat ion Ethernet Address:/ 
= . -RCVMS 1 

,ASCII /Source Ethernet Address:/ 
= .-RCVMS 2 

.ASCII /Destination SAP, Source SAP and CTL bytes:/ 
= . - RCVMS 3 

.ASCII /SNAP protocol identifier:/ 
= . - RCVMS 4 

.ASCIZ /Received data, %D. bytes:/ 
.EVEN 



, SBTTL 



Canned XID, UI and TEST messages 
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XID message 



XIDMSG: .BYTE XIDl ,XID2 ,XID3 
XIDLEN = .-XIDMSG 

; UI and TEST messages 

; for {i=0; i<MAXFRM; i++) 
(buf(i) = i%256) 

UIFMSG: 
TSTMSG: 

$$§1 = 

. REPT MAXFRM 

$$$2 = $$$1/256. 

$$$3 = $$$l-r<$$$2*256.> ; $$$3 = $$$1 mod 256. 

.BYTE $$$3 

$$$1 = $$$1+1 

.ENDR 

.EVEN 



.SBTTL . Miscellaneous pure data 

BDBLST: .WORD BDBl ; Address of first buffer descriptor 

LOGDFN: NMBLK$ 802TST , DAT , , SY , ; Log file default filename block 

GCLBLK: GCMLB$ 2 , 802 , CMDBUF , CMDLUN , , 132 . ; Get command line block 



TST802; 



NXTCMD : 



.SBTTL TST802 - Mainline code 

.PSECT $CODE I,RO 

FINIT$ 

MOV #EX$SUC,EXSTAT 

CALL ASNLNS 

BCC NXTCMD 

JMP EXIT 

CLR OPTFLG 

CLR MSGFLG 

MOV #DEVDFL, .DEVNM 

MOV #DEVDFB, .DEVNM+2 

MOVB # I SAP,. I SAP 

CLRB . DSAP 

MOV #60.,. SIZE 

MOVB #$CSXIF,.CTL 

MOV #XIDMSG, .MSADR 

MOV #XIDLEN, .MSLEN 

CLEF$S #DONE 



GCML$ 

MOVB 

BCC 

CMPB 
BNE 



#GCLBLK 
G,ERR(RO) ,R5 
20$ 

R5,#GE,E0F 
10$ 



Assume success 

Assign channel, command and error LUNs 
If CC, proceed 



Zero options flag 
Zero message type flag 
Set default device string 

( "UNA-0" ) 
Set default individual SAP (4) 
Set default destination SAP (NULL] 
Set default data block size (60) 
Set default message type (XID) 
Set default message address 

and length 

Clear exit flag 

Retrieve a command line 

Pick up error byte 

If CC, we're ready to parse 

End_of_f ile? 
If NE, no 
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JMP 


EXIT 


• EOF - just exit 


10$: 


FORMAT 


R5 , #GCLERR 


• Format error status 




LOG 


#FMTBUF,FMTL 


and report the error 




JMP 


EXIT 


Exit 


20$ : 


MOV 


it O 9 f i^-i- 






MOV 


#KEYTBL , R2 


Get address of key table 




MOV 


G.CMLD(RO) ,R3 


Get command line length 








1 1. ej\^ f get aiiocner couuuanci i inc 




MOV 


G.CMLD+2(R0) ,R4 


Get command 1 ine address 




MOV 


# ST ART, R 5 


Get address of first state 




CALL 


.TPARS 


Parse the command 1 ine 




BCC 


DOCMD 


Tf CC* nlr — omr'PPrl 




CALL 


PRSDMP 






JMP 


IN A, i V^r^iJ 




DOCMD: 










CALL 




On fin Inn filo if /T 








(Ignore possible open error) 




CALL 


OPNCHN 


Open an Ethernet channel 




BCS 


EXIT 


- exit if error 




CALL 


SETCHN 


Set the channel characteristics 




BCS 


EXIT 




; Fill 


the ring 


with receives 






DSAR$S 




Disable AST recognition 




MOV 


BDBLST,RO 


Get first buffer descriptor addr 




MOV 


#NUMBUF,R1 


Get number of buffers in ring 




CLR 


NUMRCV 


Zero received frame count 


10$ : 


MOV 


R0,RCVQIO+Q. lOSB 


; Set lOSB address 




MOV 


BD.BUF(RO) ,RCVQIO+Q. lOPL 


; Set data buffer address 




MOV 


BD.RCH(RO) ,RCVQIO+Q. IOPL+4 ; Set receive char address 




DIR$ 


#RCVQIO 


Post receive 




BCS 


EXIT 


If CS, error - all done 




SOB 


Rl,10$ 


Loop through the ring 




CLEF$S 


#DONE 






BIT 


#OP.RSP,OPTFLG 


Are we a passive responder? 




BNE 


20$ 


If NE, yes - don't send command 


; Transmit an 802.3 command PDU 






MOV 


.PHADR,XMTADR 


Set Ethernet address for transmi 




MOV 


. PHADR+ 2 , XMT ADR+ 2 






MOV 


. PHADR+4 , XMTADR+4 






MOVB 


. DSAP , XMTDSP 


• Set DSAP for transmit 




MOVB 


. ISAP,XMTSSP 


• Set SSAP for transmit 




MOVB 


.CTL,XMTCTL 


• Set CTL field for transmit 



4-66 



DECnet-RSX Programmer's Reference Manual 



MOV .MSADR,XMTQIO+Q. lOPL 

MOV .MSLEN,XMTQIO+Q. IOPL+2 

MOV #XMTBFR,XMTQIO+Q. IOPL+4 

MOV #XMTLN1,XMTQI0+Q. IOPL+6 



BIT #0P.SNP,0PTFLG 

BEQ 15$ 

MOV # . SNAP , RO 

MOV #XMTSNA,R1 

MOV #5,R2 

12$: MOVB (R0)+,(R1)+ 

SOB R2,12$ 

MOV #XMTLN2, XMTQ I 0+Q. IOPL+6 



15$: DIR$ #XMTQIO 

BCS EXIT 

TSTB CHNSB 

BMI EXIT 

20$: ENAR$S 

SREX$S #ABOAST 

WTSE$S #DONE 

DSAR$S 

CLOSE$ #LOGFIL 

DIR$ #CLSQIO 

JMP NXTCMD 



Set adr of message to XMT 
Set len of message to XMT 
Set adr of XMT char buffer 
Set len of XMT char buffer 
(Assume using only DSAP/SSAP/CTL) 

Use only DSAP/SSAP/CTL for XMT? 
If EQ, yes - no SNAP specified 

Get address of stored SNAP 

Get address of SNAP buffer 

Set number of bytes in protocol 

Move a protocol byte into buffer 

Loop until done 

Set len of transmit char buffer to 
include SNAP protocol ident 

Transmit a command PDU 
If CS, directive error 
Get an I/O error? 
If MI, yes 

Enable AST recognition 
Specify abort AST 
Wait for receive(s) 

Disable AST recognition 

Close the log file 

Close the Ethernet channel 

and process the next command 



XMTERl 
XMTER2 



EXIT: DIR$ #CLSQIO 

CLOSE$ #LOGFIL 

EXST$S EXSTAT 
EXIT$S 



Close the Ethernet channel 
Close the log file 
Try to exit-with-status 
Else, just exit 



.SBTTL AST routines 



.SBTTL 



RCVAST - channel read complete 



**-RCVAST - AST for channel read complete 



Inputs : 



(SP) = address of I/O status block 



Outputs : 

Message read from channel is formatted and logged 



RCVAST ; 



MOV 
MOV 
SAVRG 



(SP) , lOSB 
R3, (SP) 
<R4 ,R5> 



Save BDB/status block address 
Save R3-R5 
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12$: 



15$ 



17$ 



20$ 
30$ 



MOV 

TSTB 

BMI 

INC 
MOV 
MOV 

BIT 
BEQ 

MOV 
MOV 
MOV 
MOV 
MOV 



BIT 
BEQ. 

SAVRG 

MOV 

ADD 

MOV 

ADD 

MOV 

MOVB 

SOB 

RESRG 

MOV 

BR 

MOV 

SWAB 

MOV 

MOV 

MOV 

MOV 

DIR$ 

BCS 

BR 

CALL 

MOV 

MOV 

MOV 

MOV 

MOV 

DIR$ 

BCC 



I0SB,R3 

(R3) 

90$ 

NUMRCV 

BD.RCH(R3) ,R4 
BD.XCH(R3) ,R5 

#0P.RSP,0PTFLG 
20$ 



Retrieve BDB/status block address 
Receive error? 
If MI, yes 

Count one more buffer filled 
Get rcved chr buffer address 
Get xmted chr buffer address 

Are we a passive responder? 

If EQ, no - dop ' t send response 



R3,XMTQI0+Q. lOSB 
BD.BUF(R3) ,XMTQIO+Q. lOPL 
BD.STS+2(R3) ,XMTQIO+Q. IOPL+2 
BD.XCH(R3) ,XMTQIO+Q. IOPL+4 
#XC.LN1,XMTQI0+Q. IOPL+6 



Set lOSti address 

Set data buffer address 

and length 
Set xmt char address 

and length 
(Assuming DSAP/SSAP/CTL) 



#OP.SNP,OPTFLG 
15$ 

<R0,R1,R2> 
R4 ,R0 

#RC.SNM,R0 
R5,R1 

#XC.SNM,R1 
#5,R2 

(R0)+, (Rl)+ 

R2,12$ 

<R2,R1,R0> 

#XC.LN2 ,XMTQIO+Q. IOPL+6 
17$ 

RC . SPM ( R4 ) , XC . SPM ( R5 ) 
XC.SPM(R5) 

RC.CTM(R4) ,XC.CTM(R5) 

RC.SAD(R4), XC.ADR(R5) 
RC.SAD+2(R4) , XC . ADR+2 { R5 ) 
RC.SAD+4(R4) , XC . ADR+4 { R5 ) 
#XMTQIO 
90$ 
30$ 



LOGRCV 

R3,RCVQI0+Q. lOSB 
BD.BUF{R3) ,RCVQIO+Q. lOPL 
#BUFSIZ,RCVQIO+Q. IOPL+2 
BD.RCH(R3) ,RCVQIO+Q. IOPL+4 
#RC.LEN,RCVQIO+Q. IOPL+6 
#RCVQIO 
100$ 



Use only DSAP/SSAP/CTL for XMT? 
If EQ, yes - no SNAP specified 



Form pointer to received SNAP 

Form pointer to transmitted SNAP 

Set size of SNAP protocol ident 
Copy a protocol byte 
Loop until done 

Include SNAP in XMT char buffer 
(Note: SNAP supersedes DSAP/... 
Join common code 

Get the DSAP/SSAP from receive 

and swap them for response 
Set the CTL field 

Set Ethernet address for transmit 



Send response PDU 

If CS , directive error 

Don't log data while responding 

Log received data 



Set lOSB address 
Set data buffer address 

and length 
Set receive char address 
and length 
; Hang another receive 
; If CC, receive is queued 
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90$: DSAR$S ; Disable AST recognition 

SETF$S #DONE ; Wake up mainline for cleanup 



100$; 



ABOAST I 



ASNLNS ! 



10$: 



20$; 



30$; 
40$; 



OPNLOG: 



RESRG 


<R5 ,R4 ,R3> 




ASTX$S 






.SBTTL 


ABOAST - Abort 


AST 


ADD 


(SP) ,SP 




DSAR$S 




; Disable AST recognition 


SETF$S 


#DONE 


; Done 


ASTX$S 






.SBTTL 


Utility subroutines 




.SBTTL 


ASNLNS - Assign 


channel, command, error LUNs 


LUN to 


channel 




ALUN$S 


#CHNLUN, #''NX, 




BCC 


10$ 




JSR 


RO , DIRERR 




.WORD 


ASNFMl 




BR 


40$ 




LUN to 


conunand terminal 




ALUN$S 


#CMDLUN, #"TI 




BCC 


20$ 




JSR 


RO , DIRERR 




.WORD 


ASNFM2 




BR 


40$ 




1 LUN to 


output terminal 




ALUN$S 


#TILUN,#"TI 




BCC 


30$ 




JSR 


RO, DIRERR 




.WORD 


ASNFM3 




BR 


40$ 




TST 


(PC) + 




SEC 






Rb 1 URN 






.SBTTL 


OPNLOG- Open a 


log file 


.ENABL 


LSB 




BIT 


#OP.LOG,OPTFLG 


; /LOG requested? 


BEQ 


20$ 


; If EQ, no 


OPEN$A 


#LOGFIL 


; Append to file if existing 


BCC 


10$ 


; If CC, file is open 


OPEN$W 


#LOGFIL 


; Else, create a new file 
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BCC 
BIC 
BR 

10$: GTIM$S 
FORMAT 
PUT$ 
SUB 
PUT$ 

20$; RETURN 
. DSABL 

. SBTTL 

OPNCHN: 

MOV 
MOV 
MOV 
BIT 
BEQ 
CLR. 

5$: MOv' 
MOV 
BIT 
BEQ 
MOV 

7$: DIR$ 
BCC 
JSR 
.WORD 
BR 

10$: TSTB 
CLC 
BPL 
JSR 
.WORD 

20$: ERROR 
SEC 

30$: RETURN 

.SBTTL 

SETCHN: MOVB 
MOV 
MOV 
DIR$ 
BCS 
TSTB 
BMI 

BIT 
BEQ 
MOVB 
MOV 



10$ 

#OP.LOG,OPTFLG 
20$ 

#TIMBUF 

#TIMBUF,#TIMFMT 

# LOGF I L , #FMTBUF , FMTL 
#CMDBUF,R4 

# LOGF I L , tCMDBUF , R4 



If CC, file is open 
Indicate no log file in use 

and return 
Get current time 
Format time into ASCII 
Store timestamp in log file 
Compute length of command 

and log the command line 



LSB 



OPNCHN - Open channel 



.DEVNM+2,0PNQI0+Q. lOPL 

.DEVNM,OPNQIO+Q. IOPL+2 

#TMO,TIMOUT 

#OP.RSP,OPTFLG 

5$ 

TIMOUT 

TIMOUT,OPNQIO+Q. IOPL+4 
#OPNCHL,OPNQIO+Q. IOPL+10 
#OP.USR,OPTFLG 
7$ 

#OPNCL0,OPNQIO+Q. IOPL+10 

#OPNQIO 

10$ 

RO,DIRERR 

OPNFMT 

20$ 



Set "xxx-n" address 

Set "xxx-n" length 

Set timeout in seconds 

Are we passively responding? 

If EQ, no 

No timeout on receives 
Set the time-out for open 
Assume Class I service 
Opening for Class I service? 
If EQ, yes 

Else get set for user service 

Open the line 

If, CC, OPEN queued 



CHNSB 
30$ 

RO , lOERR 
OPNFMT 

#OPNCHB,#OPNCHF 



Did OPEN succeed? 
Assume yes 
If PL, yes 



Indicate failure 



SETCHN - Set chan; 

.ISAP,SETISP 
#SETBF1,SETQI0+Q. lOPL 
#SETLN1,SETQI0+Q. IOPL+2 ; 
#SETQIO ; 
20$ 

CHNSB ; 
30$ 

#OP.GSP,OPTFLG 
10$ 

.GSAP,SETGSP 

#SETBF2,SETQI0+Q. lOPL ; 



lel characteristics 

Store SAP number 

Get char buffer address 

Get char buffer length 

Enable the ISAP 

If CC, request got queued 

Did we enable an ISAP? 

If MI, no 

Enabling a group SAP? 
If EQ, no 

Store group SAP number 
Get char buffer address 
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MOV 


#SETLN2 ,SETQIO+Q. lOPL 




DIR$ 


#SETQIO 




BCS 


20$ 




TSTB 


CHNSB 




BMI 


30$ 


10$: 


BIT 


#OP.SNP,OPTFLG 




CLC 






BEQ 


50$ 




MOV 


#.SNAP,RO 




MOV 


#SETSNA,R1 




MOV 


#5,R2 


15$: 


MOVB 


(R0)+, (Rl)+ 




SOB 


R2,15$ 




MOV 


#SETBF3 ,SETQIO+Q. lOPL 




MOV 


#SETLN3 ,SETQIO+Q. lOPL 




DIR$ 


#SETQIO 




BCS 


20$ 




TSTB 


CHNSB 




CLC. 






BPL 


50$ 




BMI 


30$ 


20$: 


JSR 


RO,DIRERR 




.WORD 


SETFMT 




BR 


40$ 


30$: 


JSR 


RO, lOERR 




.WORD 


SETFMT 


40$: 


SEC 




50$: 


RETURN 




.SBTTL 


LOGRCV - Log 


'; **-LOGRCV - 


Log received data 


; Inputs: 






R3 is 


buffer descriptor block 






BD.BUF(R3) contains t 






BD.STS+2(R3) contains 




R4 is 


received characteristic 






RC.DAD(R4) contains t 






RC.SAD(R4) 






RC.SPM(R4) 






RC.CTM(R4) 


; Registers modified: 




R4 ,R5 




LOGRCV : 


TST 


BD.BUF+2(R3) 




BNE 


10$ 




JMP 


100$ 


10$: 


SAVRG 


<R0,R1,R2> 




LOG 


#RCVMS1,#RCVLN1 




ADD 


#RC.DAD,R4 



+2 ; Get char buffer length 

; Enable the GSAP 

; If CC, request got queued 

; Did we enable a GSAP? 

; If MI, no 

; Enabling a SNAP protocol ID? 

; Assume not 

; If EQ, all done 

; Copy protocol ident to buffer 



; Get char buffer address 

+2 ; Get char buffer length 

; Enable the SNAP protocol ID 

; If CC, request got queued 

; Did we enable a SNAP? 

; Assume success 

; If PL, yes - all done 

; If MI, no 



; Indicate failure 



received data 



address 
he buffer address 

the number of bytes received 
s block address 
e received destination address 
source 
DSAP/SSAP 
CTL 



; Any data to log? 

; If NE, yes 

; Else, get out 

; Log DST Ethernet address 
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MOV 

CALL 

SUB 

LOG 
ADD 
CALL 
SUB 

BIT 
BNE 

LOG 

MOV 

MOVB 

BICB 

MOVB 

MOVB 

MOV 

MOV. 

CALL 

BR 

20$: LOG 
MOV 
ADD 
MOV 
CALL 

30$: MOV 
MOV 
FORMAT 
LOG 
MOV 
CALL 

RESRG 
100$: RETURN 

.SBTTL 
.SBTTL 
.SBTTL 
.ENABL 

DIRERR: 

MOV 

SAVRG 

MOV 

ERROR 

BR 

lOERR: 

MOV 
SAVRG 
MOV 
MOV 



#6,R5 

LOGDAT 

#RC.DAD,R4 

#RCVMS2 ,#RCVLN2 
#RC.SAD,R4 
LOGDAT 
#RC.SAD,R4 

#OP.SNP,OPTFLG 
20$ 

#RCVMS3,#RCVLN3 
#FMTDAT , R2 
RC.SPM(R4) , (R2)+ 
#l,RC.SPM-i-l{R4) 
RC.SPM+1{R4) , (R2) + 
RC.CTM(R4) , (R2)+ 
#FMTDAT,R4 
#3,R5 
LOGDAT 
30$ 

#RCVMS4,#RCVLN4 

#FMTDAT,R2 

#RC.SNM,R4 

#5,R5 

LOGDAT 

BD.STS+2(R3) , R5 
R5 , FMTDAT 
#FMTDAT,#RCVMS5 
#FMTBUF,FMTL 
BD.BUF{R3) ,R4 
LOGDAT 



Log SRC Ethernet address 



Logging DSAP/SSAP/CTL? 
If NE, no - log a SNAP id 

Log DSAP/SSAP/CTL bytes 



Log SNAP protocol ID 



Received data, n. bytes 



<R2,R1,R0> 



DIRERR - Report a directive error 
lOERR - Report an I/O error 

I0ER2 - Report an I/O error (alternate entry) 

LSB 

{R0)+, FMTDAT 

<R0,R1,R2> 

$DSW,FMTDAT+2 

#FMTDAT,#ERRFM1 

10$ 



( RO ) + , FMTDAT 
<R0,R1,R2> 
CHNSB,FMTDAT+2 
CHNSB+2 ,FMTDAT+4 
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I0ER2; 



10$: 



ERROR #FMTDAT , #ERRFM2 
BR 10$ 



MOV (RO)+,FMTDAT 

SAVRG <R0,R1,R2> 

MOVB RCVSB , Rl 

MOV Rl,FMTDAT+2 

MOV RCVSB+2,FMTDAT+4 

ERROR #FMTDAT,#ERRFM2 

MOV #EX$ERR,EXSTAT 

RESRG <R2,R1,R0> 

RTS RO 

.DSABL LSB 



.SBTTL 



LOGDAT - Log data in hex 



HEX = 16. 

NOSUP = IflOOO 

BLKFIL = 1*2000 

FLDWID = 2*4000 

MASK = HEX+FLDWID+NOSUP 

NFLDS = 16. 



LOGDAT: CALL 



10$; 



20$ 



30$: 



MOV 
MOV 
CMP 
BLE 
MOV 
BEQ 

MOV 

MOVB 

MOVB 

MOVB 

MOVB 

DEC 

BLT 



$SAVAL 

#FMTBUF,RO 

#NFLDS,R3 

R3,R5 

20$ 

R5,R3 

50$ 

R3,-(SP) 
#40, (R0)+ 
#40, (R0)+ 
#40, (R0)+ 
#40, (R0)+ 
R3 
40$ 



40$: 



CLR 

BISB 

MOV 

CALL 

MOVB 

BR 

SUB 

MOV 

LOG 

SUB 

BGT 



Rl 

(R4)+,R1 
#MASK,R2 
$CBTA 
#40, (R0)+ 

30$ 

#FMTBUF,RO 
RO ,R1 

#FMTBUF,R1 

(SP)+,R5 

10$ 



(continued on next page) 



DLX Ethernet Programming Facilities 



4-73 



50$: RETURN 



.SBTTL Parser data base 



$RONLY = 1 

I STAT? STATBL,KEYTBL 



; Make tables read-only 



.SBTTL 

STATE? 
TRAN$ 

.SBTTL 

STATE? 

TRAN? 

TRAN? 

TRAN? 
STATE? 

TRAN? 

TRAN? 

TRAN? 

TRAN? 

TRAN? 

TRAN? 

TRAN? 

TRAN? 

TRAN? 

TRAN? 

TRAN? 

TRAN? 

TRAN? 

.SBTTL 

STATE? 

TRAN? 
STATE? 

TRAN? 
STATE? 

TRAN? 

.SBTTL 

STATE? 

TRAN? 
STATE? 

TRAN? 
STATE? 

TRAN? 

.SBTTL 

STATE? 
TRAN? 



Main states 



START 
$LAMDA 



Options 



OPT 

$EOS,?EXIT 
<• ;>,?EXIT 
'/ 



! DEVOPT 
! DSPOPT 
IGSPOPT 
! HDWOPT 
! ISPOPT 
! LOGOPT 
IMSGOPT 
INODOPT 
! PHYOPT 
IRSPOPT 
ISIZOPT 
"SNPOPT 
lUSROPT 



,OPT, 
,OPT, 
,OPT, 
,OPT, 
,OPT, 
,OPT, 
,OPT, 
,OPT, 
,OPT, 
,OPT, 
,OPT, 
,OPT, 
,OPT, 



OP . DEV 
OP. DSP 
OP.GSP 
OP . HDW 
OP. ISP 
OP . LOG 
OP. MSG 
OP . NOD 
OP . PHY 
OP.RSP 
OP.SIZ 
OP.SNP 
OP.USR 



,OPTFLG 
,OPTFLG 
,OPTFLG 
,OPTFLG 
,OPTFLG 
,OPTFLG 
,OPTFLG 
,OPTFLG 
,OPTFLG 
,OPTFLG 
,OPTFLG 
,OPTFLG 
,OPTFLG 



DEVOPT - /DEV[ ICE3=ddd-n 



DEVOPT 
"DEVICE" 



EQUALS 

'DEVICE, ?EX IT, STDEV 

. DSPOPT - /DSAP={n, NULL, SNAP} 

DSPOPT 
"DSAP" 

EQUALS 

!DSPID,$EXIT 

. GSPOPT - /GSA[P]=n 

GSPOPT 
"GSAP" 
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STATE$ 

TRAN$ EQUALS 
STATE$ 

TRAN$ !GSPID,$EXIT 

.SBTTL . . HDWOPT - /HAR[ DWARE ] =nn-nn-nn-nn-nn-nn 

STATE $ HDWOPT 

TRAN$ "HARDWARE" 
STATE$ 

TRAN$ EQUALS 
STATE$ 

TRAN$ !HXADR,$EXIT,STHADD 

.SBTTL . . ISPOPT - 

STATE$ ISPOPT 

TRAN$ "ISAP" , ISP0P2 

TRAN$ "SSAP" 

STATE$ ISP0P2 

TRAN$ EQUALS 
STATE$ 

TRAN$ !ISPID,$EXIT 

.SBTTL . . LOGOPT - 

STATE $ LOGOPT 

TRAN$ "LOG",$EXIT 

.SBTTL . . MSGOPT - 

STATE $ MSGOPT 

TRAN$ "MESSAGE" 
STATE$ 

TRAN$ EQUALS 
STATE$ 

TRAN$ !MSGTYP, $EXIT 

.SBTTL . . NODOPT - /N0D[E] =aa . nn 

STATE $ NODOPT 

TRAN$ "NODE" 
STATE $ 

TRAN$ EQUALS 
STATE$ 

TRAN$ !NODID,$EXIT, 

.SBTTL . . PHYOPT - /PHY [ SICAL ] =nn-nn-nn-nn-nn-nn 

STATE $ PHYOPT 

TRAN$ "PHYSICAL" 
STATE $ 

TRAN$ EQUALS 
STATE$ 

TRAN$ !HXADR, $ EXIT, STP ADD 

(continued on next page) 
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.SBTTL . . RSPOPT - /RES[PONSE] 

STATE$ RSPOPT 

TRAN$ "RESPONDER" , $EXIT 

.SBTTL . . SIZOPT - /SIZ[E]=n 

STATE$ SIZOPT 

TRAN$ "SIZE" 
STATE$ 

TRAN$ EQUALS 
STATE$ 

TRAN$ !SIZE,$EXIT 

.SBTTL . . SNPOPT - /SNA[ P ] =nn-nn-nn 

STATE$ SNPOPT 

TRAN$ "SNAP" 
STATE$ 

TRAN$ EQUALS 
STATE $ 

TRAN$ !SNAP,$EXIT 

.SBTTL . . USROPT - /USE[R] 

STATE$ USROPT 

TRAN$ "USER",$EXIT 

.SBTTL . Utility substates 

.SBTTL . . DEVICE - device string 

STATE$ DEVICE 

TRAN$ $RAD50 
STATE $ 

TRAN$ <•-> 
STATE$ 

TRAN$ $DNUMB,$EXIT 

.SBTTL . . DSPID - destination SAP number 

STATE$ DSPID 

TRAN$ "SNAP" , $EXIT,STSNP 

TRAN$ "NULL" , $EXIT,STNSP 

TRAN$ $DNUMB, $EXIT,STDSP 

.SBTTL . . GSPID - group SAP number 

STATE$ GSPID 

TRAN$ $DNUMB, $EXIT,STGSP 

.SBTTL . . HXADR - hex address 

STATE$ HXADR 

TRAN$ 'HXBYT, ,STHAD1 
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STATE $ 

TRAN$ 
STATE $ 

TRAN$ 
STATE $ 

TRAN$ 
STATE $ 

TRAN$ 
STATE $ 

TRAN$ 
STATE $ 

TRAN$ 
STATE $ 

TRAN$ 
STATE$ 

TRAN$ 
STATE $ 

TRAN$ 
STATE $ 

TR^N$ 

.SBTTL 

STATE$ 
TRAN$ 

STATE$ 
TRAN$ 

.SBTTL 

STATE$ 
TRAN$ 
TRAN$ 

.SBTTL 

STATE$ 
TRAN$ 

.SBTTL 

STATE$ 
TRAN$ 
TRAN$ 
TRAN$ 

.SBTTL 

STATE? 

TRAN$ 
STATE$ 

TRAN$ 
STATE$ 

TRAN$ 



IHXBYT, ,STHAD2 
IHXBYT, ,STHAD3 
! HXBYT , , STHAD4 

I _ 

IHXBYT, ,STHAD5 

I _ 

IHXBYT, $EXIT,STHAD6 

. HXBYT - hex byte 

HXBYT 

•HXDIG, ,STHXD1 
IHXDIG, $EXIT,STHXD2 

. HXDIG - hex digit 

HXDIG 

$DIGIT, $EXIT,STHXN 
$ALPHA, $EXIT,STHXA 



ISPID - Individual SAP number 

ISPID 

$DNUMB, $EXIT,STISP 

MSGTYP - message type 

MSGTYP 

"TEST" , $EXIT,STTST,OP.TST,MSGFLG 
"UI" , $EXIT,STUIF,OP.UIF,MSGFLG 
"XID" , $EXIT,STXID,OP.XID,MSGFLG 

NODID - node id 

NOD ID 

$DNUMB, ,STNDA 
< ' . > 

$ DNUMB , $ EX I T , STNDN 
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.SBTTL 



SIZE - data block size 



STATE$ SIZE 
TRAN$ $DNUMB, $EXIT,STSIZ 



.SBTTL 



.SBTTL 
.SBTTL 



SNAP 



- SNAP protocol identifier 



STATE$ SNAP 

TRAN$ ! HXBYT , , STSNP 1 
STATE $ 

TRAN$ ' - 
STATE$ 

TRAN$ < HXBYT , , STSNP 2 
STATE $ 

TRAN$ ' - 
STATE$ 

TRAN$ ! HXBYT , , STSNP 3 
STATE$ 

TRAN$ • - 
STATE$ 

TRAn$ ! HXBYT ,, STSNP 4 
STATE$ 

TRAN$ ' - 
STATE$ 

TRAN$ ! HXBYT, $EXIT,STSNP5 
STATE $ 

•SBTTL Parser action routines 
.PSECT $CODE 



STNDA - Set node area 
STNDN - Set node number 



.ENABL LSB 

STNDA: MOV .PNUMB,RO 

TST . PNUMH 

BNE 10$ 

CMP RO , #MXAREA 

BHI 10$ 

MOV R0,.NODID 

BR 20$ 

STNDN: MOV .PNUMB,R0 

TST . PNUMH 

BNE 10$ 

CMP RO , #MXNODE 

BHI 10$ 

MOV R0,.NODID+2 

BIT #OP.PHY,OPTFLG 

BNE 20$ 

MOVB #252, .PHADR+0 

MOVB #0, .PHADR+1 

MOVB #4, .PHADR+2 



Get area number 
Overflow into high word? 
If NE, yes - error 
Area in range? 
If HI, no - error 
Store area number 

and return 
Get node number 
Overflow into high word? 
If NE, yes - error 
Number in range? 
I f HI , no - error 
Store node number 

Already specified physical address? 
If NE, yes - use it 
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MOVB 


#0, 


PHADR+3 






; Set 


up area 


and number in .PHADR+4, 


+ 5 






MOV 


.NODID,R0 




Get area in RO 




MOV 


.N0DID+2,R1 




Get node number in Rl 




SWAB 


RO 






Get area in high byte 




ASL 


RO 






Move area into <15:10> 




ASL 


RO 










BIS 


R0,R1 






Form node address word 




MOVB 


Rl, .PHADR+4 




and store in .PHADR+4, +5 




SWAB 


Rl 










MOVB 


Rl, .PHADR+5 








BR 


20$ 






Join common code for return 


10$: 


ADD 


#2, (SP) 






REJECT TRANSITION 


^20$: 


RETURN 












.DSABL 


LSB 










.SBTTL 




STDEV - Set 


device string 




.SBTTL 




STSNP - Set 


802 


3 SNAP SAP as DSAP 




.SBTTL 




STNSP - Set 


802 


3 NULL SAP as DSAP 




. SBTTL 




STDSP - Set 


802 


3 user-specified SAP as DSAP 




.SBtTL 




STISP - Set 


802 


3 user-specified SAP as ISAP 




.SBTTL 




STSIZ - Set 


data block size 


STDEV: 


MOV 


.PSTCN, 


.DEVNM 








MOV 


.PSTPT, 


.DEVNM+2 








RETURN 












. ENABL 


LSB 








STSNP: 


MOVB 


t-^BlOlGlOlO , .DSAP 




Store the SNAP SAP 




BR 


20$ 








STNSP: 


CLRB 


.DSAP 






Store the NULL SAP 




BR 


20$ 








STDSP- 


CALL 


30$ 






Is SAP in range? 




BCS 


10$ 






If CS, no 




MOVB 


. PNUMB , 


.DSAP 




Store destination SAP 




BR 


20$ 








STGSP: 


CALL 


30$ 






Is SAP in range? 




BCS 


10$ 






If CS, no 




BIT 


#1, .PNUMB 




Valid group? 




BEQ 


10$ 






If EQ, no - it's individual 




MOVB 


. PNUMB , 


.GSAP 




Store Group SAP 




BIS 


#OP.USR,OPTFLG 




User-supplied service is needed 




BR 


20$ 








STISP 


CALL 


30$ 






Is SAP in range? 




BCS 


10$ 






• If CS, no 




BIT 


# 1 , . PNUMB 




• Is this an Individual SAP? 




BNE 


10$ 






• If NE, no - it's a group 




MOVB 


. PNUMB , 


. I SAP 




Else, store individual SAP 




BR 


20$ 








STSIZ 


CMP 


. PNUMB , #MAXFRM 




• Data block size too large? 




BHI 


10$ 






• If HI , ,yes 




TST 


. PNUMH 






■ Is it? 




BNE 


10$ 






• If NE, yes 




MOV 


. PNUMB , 


.SIZE 




; Store data block size 




BIT 


#0P . TST ! OP . U I F , MSGFLG 


; Already parse message type? 
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BEQ 20$ 

MOV .SIZE,.MSLEN 

BR 20$ 

10$: ADD #2,(SP) 
20$: RETURN 



Check if SAP is in range 



30$ 



40$ 



CMP 
BHI 
TST 
BNE 
TST 
SEC 

RETURN 
.DSABL LSB 



.PNUMB,#377 
40$ 

. PNUMH 
40$ 
(PC) + 



If EQ, no - .SIZE will get used 
Else, stuff size into message len 

REJECT TRANSITION 



Is SAP in range? 
If HI, no 
Is it? 
If NE, no 
SUCCESS (C=0) 



STTSTi 



.SBTTL 
. SBTTL 
.SBTTL 

MOVB 

MOV 

MOV 

RETURN 



STTST 
STUIF 
STXIF 

#$CSTSF, .CTL 
#TSTMSG, .MSADR 
.SIZE, .MSLEN 



Set TEST message type 
Set UI message type 
Set XID message type 



STUIF: 



MOVB 
MOV 
MOV 
RETURN 



#$CSUIF, .CTL 
#UIFMSG, .MSADR 
.SIZE, .MSLEN 



STXID: 



MOVB 
MOV 
MOV 
RETURN 



#$CSXIF, .CTL 
#XIDMSG, .MSADR 
tXIDLEN, .MSLEN 



STSNPl 
STSNP2 
STSNP3 
STSNP4 
STSNP5 



.SBTTL 

MOVB 
MOVB 
MOVB 
MOVB 
MOVB 
RETURN 



STSNPn - Set SNAP protocol ID (byte #n) 



.HXBYT, .SNAP 
.HXBYT, .SNAP+1 
.HXBYT, .SNAP+2 
.HXBYT, .SNAP+3 
.HXBYT, .SNAP+4 



, SBTTL 
, SBTTL 



STPADD - Set physical address 
STHADD - Set hardware address 



. ENABL 
STPADD: BIT 
BNE 
MOV 
MOV 
MOV 
RETURN 



LSB 

#<OP.NOD!OP.PHY>,OPTFLG ; Already specified remote address? 
10$ ; If NE, yes - all done 

.HXADR, .PHADR 
.HXADR+2 , .PHADR+2 
.HXADR+4 , ,PHADR+4 
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STHADD: 


BIT 


#<OP.PHY!OP.NOD>, 


OPTFLG 


J Already specified remote 




BNE 


10$ 








MOV 


.HXADR, .HWADR 








MOV 


.HXADR+2 , .HWADR+2 






MOV 


.HXADR+4, .HWADR+4 




10$: 


RETURN 










.DSABL 


LSB 








.SBTTL 


STHADn - 


Set hex 


address (byte #n) 


STHADl : 


MOVE 


.HXBYT, .HXADR 






STHAD2 : 


MOVB 


.HXBYT, .HXADR+1 






^THAIT? • 
o i m\LJ o • 


MOVB 


Tjvn VT^ tiv iL r*D X 
• nAoi i f • rlAAiJK+^ 






STHAD4 : 


MOVB 


.HXBYT, .HXADR+3 






STHAD5 : 


MOVB 


.HXBYT, .HXADR+4 






STHAD6 : 


MOVB 


.HXBYT, .HXADR+5 








RETURN 










.SBTTL 


STHXN - 


Convert 


a digit to hex 




. SBTTL 


STHXA - 


Convert 


an alpha to hex 


STHXN: 


MOVB 


.PCHAR,RO 




Get digit character 




SUB 


#'0,R0 




Convert to digit value 




MOVB 






and store 




RETURN 








STHXA: 


MOVB 






• Get alpha character 




CMPB 


RO,#'A 




• Is it a hex digit? 




BLO 


10$ 




• T f T.n nr> 




CMPB 


RO,#'F 




• Is it? 




BLOS 


20$ 




If LOS, yes 


10$ : 


ADD 


#2, (SP) 








BR 


30$ 




and return 


20$: 


SUB 


#<'A-10.>,R0 




Convert to value 




MOVB 


RO, .HXDIG 






30$: 


RETURN 










. SBTTL 


STHXDl - 


Set 1st 


hex digit 




. SBTTL 


STHXD2 - 


Set 2nd 


hex digit 




. ENABL 








STHXDl : 


MOVB 


.HXDIG, RO 








ASL 


RO 








ASL 


RO 








ASL 


RO 








ASL 


RO 








MOVB 


RO , . HXBYT 








BR 


10$ 






STHXD2: 


MOVB 


.HXDIG, RO 








BICB 


#'^C17,R0 








BISB 


RO , . HXBYT 






10$: 


RETURN 










. DSABL 


LSB 








.SBTTL 


PRSDMP - 


Dump parse data on syntax error 
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CALL 


$SAVAL 


MOV 


#FMTDAT,R5 


MOV 


R3, (R5)+ 


MOV 


R4, (R5)+ 


MOV 


0PTFLG, (R5) + 


MOV 


MSGFLG, (R5)+ 


MOV 


.DEVNM, (R5) + 


MOV 


.DEVNM+2, (R5)+ 


MOV 


.NDADR, (R5) + 


MOV 


.NDADR+2, (R5)+ 


MOV 


.NDADR+4, (R5)+ 


MOVB 


.ISAP, (R5)+ 


CLRB 


(R5) + 


MOVB 


.GSAP, (R5)+ 


CLRB 


(R5) + 


MOVB 


.DSAP, (R5)+ 


CLRB 


(R5) + 


MOV 


.CTL, (R5)+ 


MOV 


#.SNAP, (R5)+ 



FORMAT #FMTDAT,#PRSERR 
LOG #FMTBUF,FMTL 
RETURN 



.END TST802 



Point at binary buffer 
Store unparsed string length 

address 

Store option flags 
Store message flags 

Store device name length 
address 

Store destination Ethernet addr 



; Store individual SAP 

; as a word 

; Store group SAP 

; as a word 

; Store destination SAP 

; as a word 

; Store CTL field 

; Store SNAP protocol address 

; Format data into ASCII 

; Log the text 
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4.4.7.2 Ethernet Example 



This program uses Ethernet frame format. You can use the program to remotely 
trigger a QNA controller. 



.TITLE TRGQNA - Trigger QNA 
.IDENT /XI. 01/ 
.NLIST BEX 



Copyright (C) 1983, 1985, 1986, 1987 by 
Digital Equipment Corporation, Maynard, Mass, 



This software is furnished under a license and may be used and copied 
only in accordance with the terms of such license and with the 
inclusion of the above copyright notice. This software or any other 
copies thereof may not be provided or otherwise made available to any 
other person. No title to and ownership of the software is hereby 
transferred. 



The information in this software is subject to change without notice 
and should not be construed as a commitment by Digital Equipment 
Corporat ion . 



Digital assumes no responsibility for the use or reliability 
software on equipment which is not supplied by Digital. 



of 



Its 



.SBTTL Program Description 

This program enables remote triggering of a properly configured 
PDP-11 Q-bus system with a DEQNA that is running RSX-llS with DECnet 
This enables an operator to load a new system image into a running 
system without manually rebooting the system. 

If the system hangs or crashes the system will request a reboot 
from the network via the DEQNA. 

Notes and Cautions: 

- The processor board must be either a KDFll-BE/BF with the KDF11-B2 
bootstrap ROM update kit installed or a KDJll-B. 

- The bootstrap switches (1-8) on the processor board must be set so 
that the boot request will be directed to the DEQNA. 

Switch 
87654321 



X 

X 

X X 

X X 

X 

1 X 




1 

X X 



DEQNA unit 
DEQNA unit 1 

Console terminal is not an ANSI mode scope 
Console terminal is an ANSI mode scope 
Loop self test but no memory diagnostics 
Loop self test and memory diagnostics 



Instructions for building the task; 
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.WORD ;C.CHRL = timer value (Off) 

STMLN = .-STMBUF ;Length for set characteristics 



DPB for write to terminal 



OUT 10: 


QIOW$ 


IO.WVB,TILUN, 2 , , , 


,<0,0,40> 


RCVBUF : 


.BLKB 


100 




;Receive buffer 


RCVLN 


= .-RCVBUF 




;Length of receive buffer 


lOSB: 


.BLKW 


2 




;I/0 status block for QIOs 




.SBTTL 


Text Strings 






; Information / 


Error Messages 






ASNERR: 


. ASCIZ 


/TRG - Unable to 


ass ign 


LUN/ 


OPNERR: 


. ASCIZ 


/TRG - Unable to 


open line/ 


DSTERR : 


.ASCIZ 


/TRG - Unable to 


set protocol type or sanity timer on/ 


RCVERR: 


. ASCIZ 


/TRG - Unable to 


request 


receive data/ 


STMERR: 


. ASCIZ 


/TRG - Unable to 


set sanity timer off/ 


REBOOT : 


.ASCIZ 


/TRG - *** Remote 


trigger received -- system re-booting ***/ 




. EVEN 








LINE : 


. ASCI I 


/QNA-0/ 




;Line definition for Set Character ist i 


LINL 




. -LINE 




;Line definition length 




. EVEN 










.SBTTL 


Main Line Code 






START: : 












ALUN$S 


#TILUN, #"CO,#0 




;Assign LUN to terminal 




ALUN$S 


#DLXLUN, #"NX, #0 




; Ass ign a LUN to DLX 




BCC 


10$ 




;If CC, ok 




MOV 


#ASNERR,R0 




;Print assign LUN error msg 




CALL 


PRINT 








BR 


999$ 




; and exit 


; Open 


the line 








10$ : 












MOV 


#I0SB,R3 




;Get address of I/O status block 




MOV 


#LINE,RO 




;Get address of line to be opened 




MOV 


#LINL,R1 




;Get length of line descriptor 




QIOW$S 


#I0.X0P,#DLXLUN,#1, ,R3, , 


<R0,R1,#400> 




BCS 


20$ 




;If CS , directive error 




MOVB 


(R3) ,R1 




;Get "OPEN" QIO status 




BPL 


30$ 




;Plus, is ok 


20$ : 












MOV 


#OPNERR,R0 




;Print open error msg 




CALL 


PRINT 








BR 


99$ 




; and exit 



; Enable console carrier protocol type and set sanity timer on 



4-84 DECnet-RSX Programmer's Reference Manual 



Note that the QNA driver will refresh the timer as long as it is running 



30$; 



40$; 



50$ 



MOV 


#I0SB,R3 


;Get I/O status block address 


MOV 


#DSTBUF,R4 


;Get address of characteristics buffer 


MOV 


#DSTLN,R5 


;Get length of characteristics buffer 


CALL 


SETCHR 


;Set characteristics 


BCC 


40$ 


;If CC, success 


MOV 


#DSTERR,RO 


;Print set characteristics error msg 


CALL 


PRINT 


BR 


99$ 


;And exit 


receive to look for 


trigger message 


QIOW$S 


#I0.XRC,#DLXLUN,#1, ,#I0SB, , <#RCVBUF , #RCVLN> 


ECS 


50$ 


;If CC, directive success 


TSTB 


lOSB 


;Was the receive successful? 


BPL 


60$ 




MOV 


#RCVERR,RO 


;Print receive error msg 


CALL 


PRINT 




BR 


99$ 


;And exit 



Make sure message received is trigger message 



60$; 



MOV 


#RCVBUF,R0 


MOV 


I0SB+2,R1 


CMP 


Rl,#5 


BLT 


40$ 


CMPB 


#6, (R0)+ 


BNE 


40$ 


MOV 


#REB00T, RO 


CALL 


PRINT 



Get the message address 

Get the message length 

Is the message minimum length? 

If LT, no - try for another message 

Is this a boot message? 

If NE, no - try for another message 

Print re-boot message 



Set the sanity timer off 



MOV 


#I0SB,R3 


MOV 


#STMBUF,R4 


MOV 


#STMLN,R5 


CALL 


SETCHR 


BCC 


70$ 


MOV 


#STMERR,R0 


CALL 


PRINT 


BR 


99$ 



Get I/O status block address 

Get address of characteristics buffer 

Get length of characteristics buffer 

Set characteristics 

If CC, success 

Print set characteristics error msg 
And exit 



Switch to system state and jump to system boot 
70$: 

CALL $SWSTK,99$ ;Switch to system state 

JMP (a#173000 ;Activate system boot 
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; Error exit 
99$: 
999$: 



QIOW$S #I0.XCL,#DLXLUN,#1 
EXIT$S 



;Close the open line 
;Exit the task 



Set characteristics routine 



SETCHR: 



10$ 



PRINT; 



5$: 



10$: 
20$: 



30$: 



40$ 



y i UW 9 b 


#I0.XSC,#DLXLUN,#1, , R3 , , 


<R4,R5> ;Issue set characteristics 


BCS 


10$ 




;If CS , directive error 


i o 1 hi 


(R3 ) 




;Any problem with the QIO? 


BMI 


10$ 




; i r Mi , yes 


CMP 


#CS.SUC, 6(R4) 




;Any problem with characteristics? 


BNE 


10$ 




;If NE, yes 


mQrp 






f I nd ic3ts succGss 


SEC 






f I nd ic3ts error 


RETURN 






* Rg t ur n to caller 


message 


rout ine 






MOV 


R0,OUTIO+Q. lOPL 




;Save message address in DPB 


TSTB 






^Search for end of message 


BNE 






• (t'PT*minp^t"pH Hv niill^ 


DEC 


rvU 




•Rj^pIt iiT^ t* o mil 1 


SUB 








MOV 






• r^nH <5^\7P in nPR 


DIR$ 


if or IT T n 




f L^ L ± I l \^ ^ L L KJ L UlCOOa^C 


MOV 


#40 ,OUTIO+Q. IOPL+4 






RETURN 






;Return to caller 


. END 


START 






BEQ 


one 




; If EQ, no - .SIZE will get used 


V 


.SIZE, .MSLEN 




; Else, stuff size into message len 


BR 


20$ 






ADD 


#2, (SP) 




; REJECT TRANSITION 


RETURN 








if SAP 


is in range 






CMP 


.PNUMB,#377 




; Is SAP in range? 


BHI 


40$ 




; If HI, no 


TST 


. PNUMH 




; Is it? 


BNE 


40$ 




; If NE, no 


TST 


(PC) + 




; SUCCESS (C=0) 


SEC 








RETURN 








.DSABL 


LSB 






.SBTTL 


STTST - Set 


TEST message type 


.SBTTL 


STUIF - Set 


UI 


message type 


.SBJTL 


STXIF - Set 


XID message type 
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STTST: 



MOVB 

MOV 

MOV 

RETURN 



#$CSTSF, .CTL 
#TSTMSG, .MSADR 
.SIZE, .MSLEN 



STUIF: 



MOVB 

MOV 

MOV 

RETURN 



#$CSUIF, .CTL 
#UIFMSG, .MSADR 
.SIZE, .MSLEN 



STXID! 



STSNPl: 
STSNP2 ; 
STSNP3i 
STSNP4 ; 
STSNP5; 



MOVB 

MOV 

MOV 

RETURN 

.SBTTL 

MOVB 
MOVB 
MOVB 
MOVB 
MOVB 
RETURN 



#$CSXIF, .CTL 
#XIDMSG, .MSADR 
#XIDLEN, .MSLEN 



STSNPn - Set SNAP protocol ID (byte #n) 



.HXBYT, .SNAP 
.HXBYT, .SNAP+1 
.HXBYT, .SNAP+2 
.HXBYT, .SNAP+3 
.HXBYT, .SNAP+4 



, SBTTL 
, SBTTL 



STPADD - Set physical address 
STHADD - Set hardware address 



. ENABL 
STPADD: BIT 
BNE 
MOV 
MOV 
MOV 

RETURN 



LSB 

#<0P . NOD ! OP . PHY> , OPTFLG 
10$ 

.HXADR, .PHADR 
.HXADR+2, .PHADR+2 
.HXADR+4 , .PHADR+4 



Already specified remote address? 
If NE, yes - all done 



STHADD 


BIT 


#<OP.PHY!OP.NOD>, 


OPTFLG 


• Already 


specified 




BNE 


10$ 












MOV 


.HXADR, 


. HWADR 










MOV 


.HXADR+2 , .HWADR+2 










MOV 


.HXADR+4 , .HWADR+4 








10$: 


RETURN 














. DSABL 


LSB 












.SBTTL 




STHADn - 


Set hex 


address 


(byte #n) 


STHADl 


MOVB 


.HXBYT, 


. HXADR 








STHAD2 


MOVB 


.HXBYT, 


.HXADR+1 








STHAD3 


MOVB 


.HXBYT, 


.HXADR+2 








STHAD4 


MOVB 


.HXBYT, 


.HXADR+3 








STHAD5 


MOVB 


•HXBYT, 


.HXADR+4 








STHAD6 


MOVB 


.HXBYT, 


.HXADR+5 










RETURN 














.SBTTL 




STHXN - 


Convert 


a digit 


to hex 




.SBTTL 




STHXA - 


Convert 


an alpha 


to hex 



(continued on next page) 
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STHXN: MOVB 
SUB 
MOVB 
RETURN 

MOVB 
CMPB 
BLO 
CMPB 
BLOS 
ADD 
BR 
SUB 
MOVB 
RETURN 

.SBTTL 
.SBTTL 

.ENABL 
MOVB 
ASL 
ASL 
ASL 
ASL 
MOVB 
BR 

MOVB 
BICB 
BISB 
RETURN 
.DSABL 

.SBTTL 

T iDMP: CALL 
MOV 
MOV 
MOV 
MOV 
MOV 

MOV 
MOV 
MOV 
MOV 
MOV 



STHXA: 

10$: 
20$ : 
30$: 



STHXDl: 

STHXD2 : 
10$: 



.PCHAR,R0 
#'0,R0 
RO, .HXDIG 



Get digit character 
Convert to digit value 
and store 



.PCHAR,RO 
RO , # • A 
10$ 

RO , # • F 
20$ 

#2, (SP) 
30$ 

#<' A-10.>,R0 
RO , .HXDIG 



STHXDl - Set 1st hex digit 
STHXD2 - Set 2nd hex digit 

LSB 

.HXDIG, RO 
RO 
RO 
RO 
RO 

RO, .HXBYT 

10$ 

. HXDIG, RO 
#'^C17,R0 
RO , . HXBYT 

LSB 

PRSDMP 

$SAVAL 
#FMTDAT,R5 
R3, (R5)+ 
R4 , (R5)+ 
OPTFLG, (R5)+ 
MSGFLG, {R5)+ 

.DEVNM, (R5)+ 
.DEVNM+2, (R5)+ 
.NDADR, (R5)+ 
.NDADR+2, (R5)+ 
.NDADR+4, (R5)+ 



(jet aipna cnaracter 

Is it a hex digit? 

If LO, no 

Is it? 

If LOS, yes 

Reject transition 

and return 
Convert to value 



- Dump parse data on syntax error 

; Point at binary buffer 

; Store unparsed string length 
; address 

; Store option flags 

; Store message flags 

; Store device name length 
; address 

; Store destination Ethernet addr 
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MOVE 


. ISAP, (R5)+ 


CLRB 


(R5) + 


MOVE 


.GSAP, (R5)+ 


CLRB 


(R5) + 


MOVE 


.DSAP, (R5)+ 


CLRB 


(R5) + 


MOV 


.CTL, (R5)+ 


MOV 


#.SNAP, (R5)+ 


FORMAT 


#FMTDAT,#PRSERR 


LOG 


#FMTBUF,FMTL 


RETURN 




• END 


TST802 



; Store individual SAP 

; as a word 

; Store group SAP 

; as a word 

; Store destination SAP 

; as a word 

; Store CTL field 

; Store SNAP protocol address 

; Format data into ASCII 

; Log the text 



DLX Ethernet Programming Facilities 



4-89 



5 



DLX Point-to-Point and Multipoint 
Programming Facilities 



The Direct Line Access controller (DLX) gives programs a direct interface to the 
data link, bypassing the standard DECnet user interface. With DLX, you can com- 
municate with DECnet or non-DECnet based systems. Because DLX does not 
offer higher-level DECnet services, such as routing and guaranteed delivery, it 
can give high performance in network applications. DLX also lets you build cus- 
tomized user-level protocols that best suit your applications. 

To use DLX, you issue queued input/output (QIO) calls to the NX: device. Your 
DLX program can communicate with a DLX program on an adjacent DECnet-RSX 
or non-DECnet node, using the DECnet DDCMP protocol. Your DECnet-RSX 
node can simultaneously run multiple DECnet and DLX tasks, each possibly com- 
municating with different nodes. 

DLX is automatically built for RSX-llM-PLUS systems; it is optional for RSX- 
11 M. It is also optional for RSX-llS systems, but is required for RSX-1 IS down- 
line loads and up-line dumps. 

5.1 Prerequisites for Taslcs Using DLX 

Before your system runs a DLX program, the DLX process must be loaded and the 
circuit set. 

The person in charge of network or system management installs the network, 
usually by executing a command file that contains the command for loading DLX. 
When DLX is loaded, it resides in the common partition NT. DLX. 
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The network manager also sets the circuit, either by answering Yes to the 
NETGEN question that asks about marking the circuit for load, or by issuing the 
Network Control Program (NCP) SET LINE command. The circuit owner must be 
DLX. For information on using NCP to set the circuit, refer to the DECnet-RSX 
Guide to Network Management Utilities. 

5.2 Writing DLX Programs 

DLX programming requires a thorough knowledge of MACRO- 1 1 assembly lan- 
guage and experience in writing real-time application programs. 

Since DLX bypasses the higher levels of DECnet, you lose the services at those 
levels and must therefore include them in your application. Your programs must 
provide the following: 

Flow control DLX does not support flow control for data transfer. 

The DLX programs that run on different nodes must 
therefore synchronize with each other before transfer- 
ring data. If the tasks are unsynchronized, data can be 
lost. 

Error recovery The DLX software reports errors, but your program 

must include error recovery procedures. 

Data segmentation When transmitting data, your program must segment it; 

the buffer size must be appropriate to the controller 
devices on the communicating systems. For information 
on appropriate buffer sizes, consult your network man- 
ager. 

Note that all incoming and outgoing DLX messages are buffered in a shared net- 
work buffer pool. DECnet and other DLX tasks also use these buffers. Depending 
on the requirements of the tasks sharing the buffers, you may want to increase the 
size and/or number of buffers to maintain good throughput performance. For 
information on displaying and setting buffer sizes, refer to the DECnet-RSX net- 
work management documentation. 

Also note that you must use the /PR:0 switch to task build your DLX programs. 
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5,2.1 DLX Resources 

DLX provides macros and QIOs to use in your application. 



The DECnet macro library, NETLIB.MLB, defines the offsets and macros that DLX 
QIOs use. During NETGEN, this library is transferred to your system. The defini- 
tion macro DLXDF$ contains definitions for offsets and macros. 

Your program must issue .MCALL statements and explicitly invoke the macros, as 
in the following example: 

.MCALL DLXDF$ ; extract from macro library 



DLXDF$ ; define DLX symbols 

DLX QIO functions perform services your application will require. The QIOs for 
multipoint and point-to-point programming are: 



TO, 


XOP 


Open a circuit for your program. This gives your program 
access to the controller. 


lO 


•XIN 


Initialize the circuit after a device error. 


lO 


XTM 


Transmit a message. 


lO 


XRC 


Ready the circuit to receive a message. 


lO 


XHG 


Hang up the circuit without closing it. 


lO 


XCL 


Close the circuit. 



5.3 DLX QIOs 

DLX requests conform to normal standards for RSX-11 QIOs, including logical 
unit numbers (LUNs), event flags, I/O status blocks, asynchronous system traps 
(ASTs), and parameter lists. According to RSX-1 1 standards, you can use any one 
of the three macro formats (see Chapter 2). You can use the QIO wait option 
(QIOW$) to suspend execution of the program until the call completes. 

The rest of this chapter describes the DLX QIOs. The descriptions are in the order 
in which you will probably use the QIOs. 
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lO.XOP 



lO.XOP 

(Open a Circuit) 

5.3.1 lO.XOP — Open a Circuit 
Use: 

Issue this QIO to open a circuit for DLX transmission and reception. This QIO 
associates the LUN you specify with the circuit you specify. The circuit is then 
implicitly initiated, and the DDCMP protocol is started. 

Before your application issues the lO.XOP call, the circuit owner must be set to 
DLX; the circuit must be either ON or in SERVICE state, and the LUN must be 
assigned to NX:. With devices that implement the DDCMP protocol in software, 
such as DLl 1, DUPl 1, DZ, DHU, and DHV devices, the lO.XOP function does not 
complete until the task at the other end of the circuit also performs an open or ini- 
tialize function. 

Format: 

QIO$ lO. XOF,lun,[efn]„[status],[ast],<pl,p2,p3> 

Arguments: 

lO.XOP 

is the function code that opens. a circuit. 
lun 

is the logical unit number associated with the circuit. 
efn 

is an optional event flag number set when the call completes. 
status 

is the address of an optional 2-word status block. On completion, the block con- 
tains the QIO completion status in the low-order byte of the first word (see under 
"Completion Status"). 
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ast 

is the entry point into an optional user-written AST routine to execute after tlie 
QIO completes. 

Pl 

is the address of an ASCII string that identifies the circuit to open. 
The format is: 
dev-ctl[-circu it] [ . tributary] 

where dev is the device mnemonic, ctl is the decimal value for the controller num- 
ber, circuit is the decimal number of the circuit you are opening, and tributary 
defines the decimal number of the multipoint tributary with which to communi- 
cate. 

P2 

is the length of an ASCII string that identifies the circuit to open. 
P3 

is a word argument that specifies the timeout value. This value specifies how long 
to wait to receive a transmitted message. The low-order byte of the word desig- 
nates the receive timeout value as follows: 

timeout = for no receive timer. 
timeout = <n> 

where n is the timer value in seconds. The timer value n causes the timeout to 
have a range of w-1 to «. 

Use a zero (0) in the high-order byte of this word. 



DLX Point-to-Point and Multipoint Programming Facilities 



5-5 



lO.XOP 



Completion Status: 



IS . sue The circuit opened successfully . 

(1) 

1111^6 The specified LUN is already in use. 

lE.ALN 

(-34.) 

The LUN is not assigned to NX: . 

lE.IFC 
(-2.) 

177646 Either you identified the circuit incorrectly or it is not in the 

lE.NSF system. 

(-26.) 

177760 The circuit you specified is not available for DLX use. 

lE.PRI 

(-16.) 

177757 The specified circuit is already in use. 

lE.RSU 

(-17.) 
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lO.XIN 

lO.XiN 

(Initialize the Circuit) 

5.3.2 rO.XIN — Initialize the Circuit 

Use: 

Issue this QIO to reinitialize a circuit after a fatal device error. When you use this 
QIO, you must reset the mode and timer values. 

With devices that implement the DDCMP protocol in software, such as DLll, 
DUPll, DZ, DHU, and DHV devices, the lO.XOP function does not complete 
until the task at the other end of the circuit also performs an open or initialize 
function. 

Format: 

QIO$ lO.XIN,lun,[efn],,[status],[ast],<pl > 

Arguments: 

lO.XIN 

is the function code that initializes the circuit. 
lun 

is the logical unit number that you assigned when you opened the circuit. 
efn 

is an optional event flag number set when the call completes. 
status 

is the address of an optional 2-word status block. On completion, the block con- 
tains the QIO completion status in the low-order byte of the first word (see under 
"Completion Status"). 
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lO.XIN 



ast 

is the entry point into an optional user-written AST routine to execute after this 
call completes. 

pi 

is the timer argument. Use the format for the lO.XOP argument p3 (Section 
5.3.1). 

Completion Status: 



IS. sue 

(1) 

177761 
IE. ABO 
(-15.) 

lllllG 

lE.IFC 

(-2.) 

177733 
lE.NLN 
(-37.) 



The circuit was successfully initialized. 

The initialization attempt was aborted. Either a hardware device 
error occurred, a user issued a hang-up QIO, or the circuit was 
not hungup. 

The LUN is not assigned to NX: . 



No open circuit has the specified LUN. 
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lO.XTM 

lO.XTM 

(Transmit a Message on the Circuit) 

5.3.3 lO.XTM — Transmit a Message on the Circuit 

Issue this QIO to transmit a message. lO.XTM transfers the data from the buffer 
whose address and length you specify in pi and p2 to a network buffer for trans- 
mission. Before transmitting, you must open the circuit; before transmitting after 
a device error, you must initialize the circuit. 

Format: 

QlO$ lO. X'VM,lun,{efn\„[status\,[ast\,<pl,p2> 

Arguments: 

lO.XTM 

is the function code for transmitting a message. 
lun 

is the logical unit number associated with the circuit on which to transmit. 
efn 

is an optional event flag number set when the call completes. 
status 

is the address of an optional 2-word status block. On completion, the block con- 
tains the QIO completion status in the low-order byte of the first word (see under 
"Completion Status"). 

ast 

is the entry point into an optional user-written AST routine to execute after this 
QIO completes. 

Pl 

is the address of the user buffer that contains the message to transmit. 
P2 

is the length of the message to transmit, excluding the DDCMP header and 
checksum. 
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lO.XTM 



Completion Status: 

IS. sue 

(1) 

177761 
lE.ABO 
(-15.) 



111115 
lE.DNR 
(-3.) 

111116 

lE.IFC 

(-2.) 

177733 
lE.NLN 
(-37.) 

177772 

lE.SPC 

(-6.) 



The message was successfully transmitted. 



The transmission was aborted because you or the remote user 
issued a hang-up QIO or because an unrecoverable error 
occurred in the hardware device. When a message transmission 
completes with an lE.ABO code, the circuit is hung up. You 
must either initialize or close and reopen the circuit before 
using it again. 

The hardware device was not ready. The circuit was hung up 
and not reinitialized. 



The LUN is not assigned to NX:. 



No open circuit has the specified LUN. 



The transmit buffer is too large. 
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lO.XRC 

lO.XRC 

(Receive a Message on the Circuit) 

5.3.4 lO.XRC — Receive a Message on the Circuit 

Issue this QIO to receive a message from the remote node. The circuit must 
already be initialized. You must issue lO.XRC to get any data that a remote node 
sends. If a remote node sends data, but you have not issued lO.XRC, you get an 
error report when you next issue this QIO. 

Format: 

QIO$ lO. XRC,lun,[efn]„[status],[ast],<pl,p2> 

Arguments: 

lO.XRC 

is the function code for receiving a message. 
lun 

is the logical unit number associated with the circuit on which to receive the mes- 
sage. 

efn 

is an optional event flag number set when the call completes. 
status 

is the address of an optional 2-word status block. On completion, the block con- 
tains the QIO completion status in the low-order byte of the first word (see under 
"Completion Status"). 

ast 

is the entry point into an optional user-written AST routine to execute after this 
call completes. 

Pl 

is the address of the user buffer to receive the message. 
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lO.XRC 



P2 

is the length in bytes to allocate for the receive buffer. The length of the received 
message cannot exceed the size of the system buffer, regardless of the length that 
you specify for p2. 

Completion Status: 

IS. sue You successfully received a message from the remote node. The 

(1) second word of the I/O status block contains the number of 

bytes you received. 

1 7776 1 The receive function was aborted. Either you or the remote user 

IE. ABO issued a hang-up QIO, or an unrecoverable hardware device 

(-15.) error occurred. When a receive is aborted, the circuit is hung 

up. You must either initialize or close and reopen the circuit 

before using it again. 

1 77763 Either a message was received before a receive QIO was issued 

lE.DAO and the data was lost or the user buffer was too small, and the 

(-13.) message was truncated. The user buffer length is in the second 

word of the I/O status block. 

1 77775 The hardware device was not ready. The circuit was hung up 
lE.DNR and not reinitialized. 

(-3.) 

1 77776 The LUN is not assigned to NX: . 
lE.IFC 

(-2.) 

177733 No open circuit has the specified logical unit number . 

lE.NLN 

(-37.) 

1 7764 1 A timeout condition occurred. No message arrived within the 

lE.TMO timer interval that you specified when you opened or initialized 

(-95.) the circuit. 
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lO.XRC 

111114 An error occurred on the circuit. The second word of the I/O 

lE.VER status block contains the error code. The error codes are as fol- 

(-4.) lows: 

1 0036 1 DDCMP transmit error threshold exceeded 

100362 Operation aborted 

1 00363 Message received without receive pending 

100364 Start received 

100366 Circuit physically disconnected 

100370 General error 

100374 DDCMP reply timeout threshold exceeded 

100376 DDCMP receive error threshold exceeded 
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lO.XHG 
lO.XHG 

(Hang Up the Circuit) 

5.3.5 lO.XHG — Hang Up the Circuit 
Use: 

This QIO stops operations on a circuit. lO.XHG does not close a circuit, but to 
resume operations, you must either initialize or close and reopen the circuit. 

Format: 

QIO $ lO . XHG , lun , [efn] , , [status] , [ast] 

Arguments: 

lO.XHG 

is the function code that hangs up the circuit. 
lun 

is the logical unit number associated with the circuit. 
efn 

is an optional event flag number set when the call completes. 
status 

is the address of an optional 2-word status block. On completion, the block con- 
tains the QIO completion status in the low-order byte of the first word (see under 
"Completion Status"). 

ast 

is the entry point into an optional user-written AST routine to execute after this 
call completes. 
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lO.XHG 



Completion Status: 

IS.SUC 

(1) 

177776 

lE.IFC 

(-2.) 

177733 
lE.NLN 
(-37.) 



This circuit was hung up. 

The LUN is not assigned to NX:. 

No open circuit has the specified LUN. 
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lO.XCL 
lO.XCL 

(Close the Circuit) 

5.3.6 lO.XCL — Close the Circuit 

Use: 

Issue the lO.XCL call to close an open circuit and stop the DDCMP protocol. If 
you have a dial-up connection, the circuit will hang up only after the close com- 
pletes. 

Format: 

QIO$ lO. XCL,lun,[efn]„[status],[ast] 

Arguments: 

lO.XCL 

is the function code that closes the circuit. 
lun 

is the logical unit number associated with the circuit. 
efn 

is an optional event flag number set when the call completes. 
status 

is the address of an optional 2-word status block. On completion, the block con- 
tains the QIO completion status in the low-order byte of the first word (see under 
"Completion Status"). 

ast 

is the entry point into an optional user-written AST routine to execute after this 
call completes. 
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lO.XCL 



Completion Status: 

IS. sue 

(1) 

177776 

lE.IFC 

(-2.) 

177733 
lE.NLN 
(-37.) 



The circuit was successfully closed. 
The LUN is not assigned to NX:. 

No open circuit has the specified LUN. 
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5.3.7 Programming Examples 

The following two programs use DLX to send and receive data. These examples 
are also included in your tape or disk kit. 
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5.3.7.1 Transmit Example 



The XTS program reads data from a user or an indirect command file and trans- 
mits the data to the cooperating XTR program on a remote node. 



.TITLE XTS - DLX TRANSMITTER 
.IDENT /vol. 01/ 



Copyright (C) 1983, 1985, 1986, 1987 by 
Digital Equipment Corporation, Maynard, Mass. 

This software is furnished under a license and may be used and copied 
only in accordance with the terms of such license and with the 
inclusion of the above copyright notice. This software or any other 
copies thereof may not be provided or otherwise made available to any 
other person. No title to and ownership of the software is hereby 
transferred . 

The information in this software is subject to change without notice 
and should not be construed as a commitment by Digital Equipment 
Corporat ion . 

Digital assumes no responsibility for the use or reliability of its 
software on equipment which is not supplied by Digital. 



The XTS program transmits data across an "error free" circuit to a 
receiver task. The data can be read in from a user at a terminal or 
or from an indirect command file. The receiver task, XTR, echoes the 
received data back over the circuit. 

You must run this program on a system that supports write break-throughs. 

To assemble, use the following command string: 

MAC XTS,XTS/-SP/LI :TTM=IN: [ 130 , 10 ]NETLIB/ML , IN: [200,200]XTS 

To task build, use the following command string: 

XTS/PR:0,XTS/-SP=XTS, IN: [ 130 , 10 ]NETLIB/LB:GCL 
/ 

STACK=30 
UNITS=4 

ASG=TI:1:2:3:4 
TASK=. . .XTS 

// 

Note: The IN: device must be the DECnet distribution device 

after the PREGEN procedure (if any) has been performed. 

The following is an example of the XTS-XTR dialog: 

>XTS 

LINE: DMC-0 

XTS>THIS IS A TEST OF XTS-XTR 
THIS IS A TEST OF XTS-XTR 

(continued on next page) 
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XTS>TESTING 
TESTING 



XTS>^Z 



XTR must be running on the remote system in order to receive the message 
from XTS and return an echo. 

.SBTTL LOCAL MACROS 

.MACRO EPRINT ERRMSG 

MOV # ERRMSG, RO 

CALL $EPRINT 

.ENDM EPRINT 

.SBTTL MACRO CALLS 



.MCALL 
.MCALL 

DLXDF$ 

.SBTTL 



QIOW$ , QIO$ , QIOW$S , ALUN$S , EXIT$S , EXST$S , FSRSZ$ , ASTX$S 
GCL$ ,GCLDF$,CALLR,DLXDF$ 



CONSTANTS 



;Define DLX function codes 



LUN assignments: 

TILUN=1 
CHNLUN=2 
ERRLUN=3 
CMDLUN=4 

Event flag assignments; 

TIEFN=1 
CHNEFN=2 
ERREFN=3 
CMDEFN=4 



;LUN for TI 

;LUN for error free circuit 

;LUN for errors 

;LUN for command lines 



;Event flag for terminal I/O 

;Event flag for circuit 

;Event flag for error messages 

; Event flag for command lines 



.SBTTL DATA 
Define GCL parameters 

GCLDF$ CMDLUN , CMDEFN , <XTS> , CMDBUF ,80, 
Def ine FSR size 



; DPBs 
. * * * * 

WRITE: 
ERDPB: 



FSRSZ$ 

QIOW$ 
QIOW$ 



;Room for 1 file (GCL) 



IO.WVB,TILUN,TIEFN, , , ,<0,0,4d> 
IO.WVB,ERRLUN,ERREFN, , , ,<0,0,40> 



RECl: QIO$ 10. XRC, CHNLUN, , ,R1SB, RECAST, <R1BUF, 80. > 
REC2: QIO$ 10. XRC, CHNLUN, , ,R2SB, RECAST, <R2BUF, 80. > 
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CLOSE: QIOW$ IO.XCL,CHNLUN,CHNEFN 

Exit-with-status word 

EXSTAT: .BLKW 1 ;Exit Status 

Circuit I/O status block 

CHNSB: .BLKW 2 

AST saved I/O status block 

lOSB: .BLKW 1 

Circuit receive I/O status blocks 

RISB: .BLKW 2 ;Status of first receive 

.WORD RIBUF ; Address of buffer 

.WORD HNGRCl ;Address of receive posting routine 

R2SB: .BLKW 2 ;Status of second receive 

.WORD R2BUF ; Address of buffer 

.WORD HNGRC2 ;Address of receive posting routine 

Buffer for command line 

CMDBUF: .BLKB 82. 
.EVEN 

Circuit receive buffers 

RIBUF: .BLKB 80. 
R2BUF: .BLKB 80. 
.EVEN 

**** 

TEXT STRINGS: 
**** 

Header for error messages 
XTSEM: .ASCIZ /XTS -- / 

Temporary prompt 
PROMPT: .ASCIZ <15><12>/LINE: / 
Error messages 

. ENABL LC 

.NLIST BEX 

GCLERR: .ASCIZ /Command line read error/ 

NSFERR: .ASCIZ /No such command file/ 

DLXERR: .ASCIZ /DLX not loaded/ 

OPNERR: .ASCII /Unable to open line — / 

BUFOPN: .BLKB 7 

XMTERR: .ASCII /Error transmitting data — / 

BUFXMT : . BLKB 7 

RECERR: .ASCII /Error receiving data — / 

(continued on next page) 
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BUFREC: .BLKB 7 

.LIST BEX 
.EVEN 

.SBTTL XTS - XTS MAIN LINE 
XTS — Main line of XTS code 

XTSEP: : 





MOV 


#EX$SUC,EXSTAT 




; Assign LUN to 


circuit 






ALUN$S 


#CHNLUN, #"NX, #0 






BCC 


10$ 


;If CC, all okay 




EPRINT 


DLXERR 


;Else, assume DLX not load 




BR 


EXIT 


;and leave 


; Prompt user for line ID 




10$: 


MOV 


$CLPMT, -(SP) 


;Save current prompt 




MOV 


# PROMPT, $CLPMT 


;Prompt string 




CALL 


GCL 


;Get a command line 




MOV 


(SP) +, $CLPMT 


;Restore prompt 




BCS 


EXIT 


;If CS, assume EOF 




TST 


R5 


;Blank line? 




BEQ 


10$ 


;If EQ, yes - try again 


; Open 


access to the line 






QIOW$S 


#IO.XOP,#CHNLUN,#CHNEFN, ,#CHNSB, ,<R4,R5> 




BCS 


15$ 


;IF CS, error 




MOVB 


CHNSB,R1 


; Successful? 




BPL 


20$ 


;If PL, yes 




MOV 


#BUFOPN, RO 


;Else, get buffer address 




CLR 


R2 


;Zero suppression 




CALL 


$CBOMG 


; Convert number 




CLRB 


(RO) 


;Make string ASCIZ 


15$: 


EPRINT 


OPNERR 


;Open error 




BR 


EXIT 




; Hang 


an asynchronous read on line 




20$: 


CALL 


HNGRCl 






CALL 


HNGRC2 






BCS 


EXIT 


;If CS, error 


; Get 


command line 




30$: 


CALL 


GCL 


;Get command line 




BCS 


EXIT 


;If CS, assume EOF 




TST 


R5 


;Empty line? 




BEQ 


30$ 


;If EQ, yes - try again 


; Transmit the 


buffer 






CALL 


XMIT 


;Transmit the buffer 




BCC 30$ 




;If CC, get next message 
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; Close the line 

EXIT: DIR$ #CLOSE 

; Exit XTS 

;Try to ex i t-wi th-status 
;Else, just exit 

.SBTTL GCL - GET COMMAND LINE 

+ 

**-GCL-Get command line 



EXST$S EXSTAT 
EXIT$S 



This routine reads a command line for XTS. The input can be from 

TI; or from an indirect command file. Return with carry set for error 

or EOF. 



Inputs : 

None 



Outputs : 

R4=address of command line 





R5 = s i ze 


of command line in 


bytes 






Carry bit set/cleared 






; Effects: 










R4,R5 modified 






GCL: 


GCL$ 






;Get command line 




MOV 


$CLI0S,R5 




;Point to I/O status block 




TSTB 


(R5) 




; Error? 




BGT 


40$ 




; I f GT , no 




CMPB 


frIE.EOF, (R5) 




;End of file? 




BEQ 


30$ 




; I f EQ, yes - set C and return 




CMPB 


# I E.ABO, (R5) 




;Was read killed by receive? 




BEQ 


30$ 




;If EQ, yes - return with C-SET 




CMPB 


#IE.NSF, (R5) 




;No such file error? 




BNE 


10$ 




; I f NE , no 




EPRINT 


NSFERR 




;Else, say so 




CALL 


ECHO 




;Echo command line 




CLR 


R5 




;Set command line length to 




BR 


50$ 




; and return empty 


10$: 


EPRINT 


GCLERR 




;Print get command line error 


20$: 


TSTB 


$CLEVL 




;Terminal input? 




BNE 


30$ 




;If NE, no - fatal error 


30$: 


BR 


GCL 




;Else, prompt again 


SEC 






;Set carry 




BR 


50$ 




; and exit 


; Get 


size and 


address of command 


1 ine 




40$: 


MOV 


$CLBUF,R4 




;Get address of command line 




MOV 


2(R5) ,R5 




;Get size of command line 




CLC 






;Set success 
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50$: 



RETURN ; Return 

•SBTTL HNGRCl - HANG ASYNCHRONOUS READ ON LINE 



**-HNGRCl - Hang an asynchronous read on the circuit 
**-HNGRC2 - 

Inputs : 

None 

Outputs: 

Receive hung on line 



.ENABL LSB 



HNGRCl 



HNGRC2 



10$: 
20$: 



CALL 
DIR$ 
ECS 
BR 



CALL 
DIR$ 
BCC 

EPRINT 
SEC 

RETURN 
.DSABL 



$SAVAL 
#REC1 
10$ 
20$ 



$SAVAL 

#REC2 

20$ 

RECERR 



LSB 



;Save all registers 
;Hang receive 
;If CS, error 

;and continue in common code 



;Save all registers 
;Hang receive 
;If CC, success 
;Receive error 
(•Indicate failure 
; Return 



.SBTTL XMIT - TRANSMIT DATA OVER LINE 
**-XMIT - Transmit data over line 



Inputs; 



R4 = Address of data 
R5 = Length of data 



Outputs: 

Data transmitted 



XMIT! 



10$: 
20$: 



QIOW$S #IO.XMT,#CHNLUN, #CHNEFN, ,#CHNSB, ,<R4,R5> 



BCS 

MOVB 

BPL 

MOV 

CLR 

CALL 

CLRB 

EPRINT 

SEC 

RETURN 



10$ 
CHNSB,R1 
20$ 

#BUFXMT,R0 
R2 

$CBOMG 

(RO) 

XMTERR 



If CS, error 
Successful? 
If PL, yes 

Else, get buffer address 
Zero suppression 
Convert number 
Make string ASCIZ 
Transmit error 
Indicate failure 



.SBTTL RECAST - AST FOR CHANNEL READ COMPLETE 
**-RECAST - AST for circuit read complete 



Inputs: 



(SP) = Address of I/O status block 
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; Outputs: 

; 1. Another read hung on channel (if last receive succeeded) 

; 2. Buffer read from channel is echoed on terminal 

RECAST: 



MOV 


(SP) , lOSB 


;Save I/O status block address 


MOV 


Rl , (SP) 


;Save Rl 


MOV 


I0SB,R1 


;Get I/O status block address 


TSTB 


(Rl) 


;Successful completion? 


BPL 


10$ 


;If PL, yes - write it out 


CALLR 


EXIT 


;Else, close line and exit 


MOV 


2(R1) ,WRITE+Q. IOPL+2 


;Set length of buffer to write 


MOV 


4 (Rl ) ,WRITE+Q. lOPL 


;Set buffer address 


DIR$ 


#WRITE 


;Write buffer to terminal 


CALL 


(a5(Rl) 


;Hang another receive 


MOV 


(SP)+,R1 


;Restore Rl 


ASTX$S 






.SBTTL 


$EPRINT -- PRINT ERROR 


MESSAGE 



-$EPRINT- Print error message 



Prints the specified error message prefixed by "XTS -- ". 
Sets the exit-status as "EX$ERR". 



Inputs : 

RO=Address of message 

Outputs : 

Error message printed on TI 
EXSTAT = EX$ERR 



Effects: 

No registers modified 



.ENABL LSB 



$EPRINT; 



PRINT2 

5$: 

10$: 



MOV RO,-(SP) 

MOV #EX$ERR, EXSTAT 

MOV #44 ,ERDPB+Q. IOPL+4 

MOV #XTSEM,RO 

CALL 5$ 

MOV #53 ,ERDPB+Q. IOPL+4 

MOV (SP)+,RO 

MOV RO ,ERDPB+Q. lOPL 

TSTB (R0)+ 

BNE 10$ 

DEC RO 

SUB ERDPB+Q. IOPL,R0 

MOV RO , ERDPB+Q. IOPL+2 

DIR$ #ERDPB 

MOV #40 , ERDPB+Q. IOPL+4 

RETURN 

.DSABL LSB 



;Save RO 

;Set exit status to "ERROR" 
;Set vertical format to prompt 
;Get prefix message 
;Print prefix 

;Set vert, format to overprint 
;Get address of message 



Set address of message 
Null byte? 

If NE, no - keep looking 
Don't count null 
Calculate length of string 
Set length of string 
Issue directive 

Restore vertical format to normal 



.SBTTL ECHO - ECHO COMMAND LINE 
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+ 

**-ECKO-Echo command line 



This routine echoes the current command line if it came from an indirect 
command file. 

I nputs : 

$CLEVL=Indicates command file level 
SCLBUF=Pointer to start of ASCIZ command line 

Outputs : 

LINE FEED appended to command line and command line echoed on TI: 

Effects : 

RO, Rl modified 

ECHO: 

TSTB $CLEVL ;Command from terminal? 

3EQ 10$ ;If EQ, yes - don't echo 

MOV $CLBUF,RO ;Point to command line 

CALL PRINT2 ;Print line on error LUN 

10$: RETURN 

.END XTSEP 
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5.3.7.2 Receive Example 

The XTR program uses DLX QIOs to receive data from the cooperating XTS task 
on a remote node. 



.TITLE XTR - DLX RECEIVER 
.IDENT /vol. 01/ 

; Copyright (C) 1983, 1985, 1986, 1987 by 

; Digital Equipment Corporation, Maynard, Mass. 

; 

; This software is furnished under a license and may be used and copied 

; only in accordance with the terms of such license and with the 

; inclusion of the above copyright notice. This software or any other 

; copies thereof may not be provided or otherwise made available to any 

; other person. No title to and ownership of the software is hereby 

; transferred. 

; 

; The information in this software is subject to change without notice 

; and should not be construed as a commitment by Digital Equipment 

; Corporation. 

; 

; Digital assumes no responsibility for the use or reliability of its 

; software on equipment which is not supplied by Digital. 

; 

; 

; The XTR program receives and echoes data over a circuit. Use it in 
; conjunction with the XTS program. 

; To assemble, use the following command string: 

; MAC XTR,XTR/-SP=IN: [130,10]NETLIB/ML, IN: [200,200]XTR 

; To task build, use the following command string: 

; XTR/PR:0,XTR/-SP=XTR, IN: [ 1 30 , 10 ] NETLIB/LB : GCL 

/ 

STACK=30 
UNITS=3 
ASG=TI:1:2:3 
; TASK=...XTR 

// 

; Note: The IN: device must be the DECnet distribution device 
; after the PREGEN procedure (if any) has been performed. 

; The following is an example of the XTS-XTR dialog: 

>XTS 

LINE: DMC-0 

XTS>THIS IS A TEST OF XTS-XTR 
THIS IS A TEST OF XTS-XTR 

XTS>TESTING 
TESTING 

; XTS>'"Z 
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start XTR before starting the remote XTS program. Start XTR as follows: 



>XTR 

LINE: DUP-0 

When you are finished with these programs, abort XTR. 

.SBTTL LOCAL MACROS 

.MACRO EPRINT ERRMSG 

MOV #ERRMSG,RO 

CALL $EPRINT 

.ENDM EPRINT 

.SBTTL MACRO CALLS 



.MCALL 
.MCALL 



QIOW$ ,QIO$,QIOW$S, ALUN$S,EXIT$S,EXST$S,ASTX$S,WTSE$S 
GCL$ , GCLDF$ , DLXDF$ , DLXBUF 



DLXDF$ 

. SBTTL CONSTANTS 
Receive buffer size 

BUFSIZ = 90. 

LUN assignments: 

TILUN=1 

CHNLUN=2 

ERRLUN=3 

Event f^aq assignments: 

TIEFN=1 
CHNEFN=2 
ERREFN=3 
D0NE=4 



:Define DLX function codes and overhead 



;LUN for TI 

;LUN for error-free circuit 
;LUN for errors 



/Event flag for terminal I/O 

;Event flag for circuit 

;Event flag for error messages 

;Event flag signaling completion 



.SBTTL DATA 



Define GCL parameters 

GCLDF$ T I LUN, T lEFN, <L INE> ,R1BUF, BUFSIZ 

**** 

DPBs 
**** 



ERDPB: QIOW$ 10 . WVB , ERRLUN, ERREFN , , , , <0 , , 40> 

RECl: QIO$ 10. XRC, CHNLUN, , ,R1SB, RECAST, <R1BUF,BUFSIZ> 

REC2: QIO$ 10. XRC, CHNLUN, , ,R2SB, RECAST, <R2BUF,BUFSIZ> 



5-28 



DECnet-RSX Programmer's Reference Manual 



XMT: QIOW$ IO.XTM,CHNLUN,CHNEFN, ,CHNSB, ,<0,0> 
START: QIOW$ 10. XIN, CHNLUN, CHNEFN, , CHNSB 
CLOSE: QIOW$ I O.XCL, CHNLUN, CHNEFN 

; Circuit I/O status block 
CHNSB : . BLKW 2 

; Temporary location to contain lOSB address 

lOSB: .BLKW 1 
TEMP: .BLKW 1 



Circuit receive I/O status blocks 

RISB: .BLKW 2 

.WORD RIBUF 
.WORD HNGRCl 



R2SB: 



• BLKW 
.WORD 
.WORD 



2 

R2BUF 
HNGRC2 



;Status of first receive 
;Address of buffer 

;Address of receive posting routine 

;Status of second receive 
/Address of buffer 

/Address of receive posting routine 



Circuit receive buffers 

DLXBUF R1BUF,BUFSIZ 
DLXBUF R2BUF,BUFSIZ 
.EVEN 



/First buffer descriptor 
/Second buffer descriptor 



/ Text strings; 

t Ifkltit 



/ Header for error messages 
XTREM: .ASCIZ /XTR — / 



Error messages 





. ENABL 




.NLIST 


GCLERR: 


•ASCIZ 


DLXERR: 


.ASCIZ 


OPNERR: 


.ASCII 


BUFOPN: 


.BLKB 


XMTERR : 


.ASCII 


BUFXMT : 


.BLKB 



LC 
BEX 

/Command line read error/ 
/DLX not loaded/ 
/Unable to open line — / 
7 

/Error transmitting data -- 
7 
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RECERR: .ASCII /Error receiving data — / 1 

BUFREC: .BLKB 7 

.LIST BEX 

.EVEN 

.SBTTL XTREP - XTR MAIN LINE 

XTREP — Main line of XTR code 

Prompt user for line to open and loop all received messages over the same line 

Inputs : 

None . 

Outputs : 

Loop all messages indefinitely. 



XTREP: : 

CLR- R3 

Assign LUN to circuit 

ALUN$S #CHNLUN,#"NX,#0 

BCC 10$ 

EPRINT DLXERR 

BR 99$ 

Prompt user for line ID 



10$ 



CALL 
BCS 
TST 
BEQ 



GCL 
99$ 
R5 
10$ 



Open access to the line 

QIOW$S #IO.XOP,#CHNLUN, #CHNEFN 



BCS 

MOVB 

BPL 

MOV 

CLR 

CALL 

CLRB 



15$ 

CHNSB,R1 
20$ 

#BUFOPN,R0 
R2 

$CBOMG 
(RO) 



15$ 



EPRINT OPNERR 



BR 



99$ 



Hang an asynchronous read on line 



20$: 



CALL 
BCS 



CALL 
BCS 



HNGRCl 
99$ 

HNGRC2 
99$ 



;If CC, all okay 

;Else, assume DLX not loaded 

;and leave 



;Get a command line 
;If CS, assume EOF 
;Blank line? 
; I f EQ, yes - try again 



,#CHNSB, ,<R4,R5> 
;If CS, error 
;Successf ul? 
;If PL, yes 

;Else, get buffer address 
;Zero suppression 
;Convert number 
;Make string ASCIZ 
;Open error 



;If CS, error 

;Hang second receive 
; I f CS , error 
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The rest is AST-driven. Pretend we are waiting for something. 

WTSE$S #DONE ;Wait for completion (never happens! 

99$: 



;Close down the line 
;Exit 



DIR$ #CLOSE 
EXIT$S 

.SBTTL GCL - GET COMMAND LINE 

h 

**-GCL-Get command line 

This routine reads a command line for XTR. The input can be from TI : 

or from an indirect command file. Return with carry bit set for error or EOF, 

Inputs : 

NONE 

Outputs : 

R4=ADDRESS OF COMMAND LINE 
R5=SIZE OF COMMAND LINE IN BYTES 
C-BIT SET/CLEARED 

Effects: 

R4,R5 MODIFIED. 



GCL; 



GCL$ 
MOV 
TSTB 
BGT 

CMPB 
BEQ 

CMPB 
BEQ 



$CLI0S,R5 

(R5) 

40$ 

#IE.EOF, (R5) 
30$ 

#IE. ABO, (R5 ) 
30$ 



10$: 
20$: 



30$: 

Get 
40$: 

50$: 



EPRINT GCLERR 

TSTB $CLEVL 

BNE 30$ 

BR GCL 
SEC 

BR 50$ 

size and address of command line 

MOV $CLBUF,R4 

MOV 2(R5),R5 
CLC 



Get command line 

Point to I/O status block 

Error? 

If GT, no 

End of file? 

If EQ, yes - set carry and return 

Was read killed by receive? 

If EQ, yes - return with carry set 

Print get command line error 

Terminal input? 

If NE, no - fatal error 

Else, re-prompt 

Set carry 

and exit 



:Get address of command line 
:Get size of command line 
;Set success 



RETURN ; Global return 

.SBTTL HNGRCl - HANG ASYNCHRONOUS READ ON LINE 
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.SBTTL HNGRC2 - HANG SECOND ASYNCHRONOUS READ 

**-HNGREC - Hang an asynchronous read on the circuit 
**-HNGRC2 - Hang second asynchronous read on circuit 

Inputs : 

None . 



Outputs: 

Receive hung on line 



HNGRCl : 

HNGRC2 : 

10$: 
20$: 



.ENABL LSB 



DIR$ 

ECS 

BR 

DIR$ 
BCC 

EPRINT 
SEC 

RETURN 
.DSABL 

.SBTTL 



#REC1 

10$ 

20$ 

#REC2 
20$ 

RECERR 



LSB 
XMIT 



;Hang read 
;If cs, error 

;And continue in common code 

;Hang read 
;If CC return 
;Receive error 
; Indicate failure 



TRANSMIT DATA OVER LINE 



**-XMIT - Transmit data over line 



Inputs : 

None 



; Outputs: 

; Data transmitted 

XMIT: 



MOV 


R1,-(SP) 


Save Rl 


DIR$ 


#XMT 


Transmit data 


BCS 


10$ 


If CS, error 


MOVB 


CHNSB,R1 


Successful ? 


BPL 


20$ 


If PL, yes 


MOV 


#BUFXMT,R0 


Else, get buffer address 


CLR 


R2 


Zero suppression 


CALL 


$CBOMG 


Convert number 


CLRB 


(RO) 


Make string ASCIZ 


EPRINT 


XMTERR 


Transmit error 


SEC 




Indicate failure 


MOV 


(SP)+,R1 


Restore Rl 


RETURN 






.DSABL 


LSB 




.SBTTL 


RECAST - AST FOR CIRCUIT 


READ COMPLETE 



+ 

**-RECAST - AST for circuit read complete 



Inputs: 
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(SP) = ADDRESS OF I/O STATUS BLOCK 



Outputs: 

1. Another read hung on circuit 

2. Buffer read from circuit is echoed over line 



RECAST; 



5$; 



10$: 



20$: 



MOV 


(SP) ,TEMP 




MOV 


Rl, (SP) 




MOV 


TEMP,R1 




TSTB 


(Rl) 




BPL 


10$ 




TST 


R J 




BNE 


20$ 




INC 


R3 




DIR$ 


# START 




BCC 


5$ 




lOT 






TSTB 


CHNSB 




BPL- 


20$ 




lOT 






CLR 


R3 




MOV 


2(R1) ,XMT+Q. 


IOPL+2 


BEQ 


20$ 




MOV 


4(R1) ,XMT+Q 


lOPL 


CALL 


XMIT 




CALL 


@6(R1) 




MOV 


(SP)+,R1 




ASTX$S 







Save lOSB address 
Save Rl 
Rl -> lOSB 

Successful completion? 

If PL, yes - transmit message 

Been through this code last time? 

Yes - post receive and return 

Mark 

Else, restart the line 

If success, continue 

Else abort 

Success? 

Yes - continue 

Else fatal error - abort 

Clear flag 

Set length of buffer to transmit 
If EQ, no buffer to transmit? 
Set address of buffer 
Echo message back over line 
Hang another receive on circuit 
Ignore any errors 
Restore Rl 
Exit AST 



.SBTTL $EPRINT -- PRINT ERROR MESSAGE 
**-$EPRINT-Pr int error message 



Prints the specified error message, with an "XTR -- " prefix. 
Sets the exit-status as "EX$ERR". 



; Inputs: 

; R0=Address of message 

; Outputs: 

; Error message printed on TI : 

; Effects: 

; No registers modified 

$EPRINT: 



MOV 


RO,-(SP) 


;Save RO 


MOV 


#44 ,ERDPB+Q. IOPL+4 


;Set vertical format to prompt 


MOV 


#XTREM,RO 


;Get prefix message 


CALL 


5$ 


jPrint prefix 


MOV 


#53 ,ERDPB+Q. IOPL+4 


;Set vert, format to overprint 


MOV 


(SP)+,RO 


;Get address of message 


MOV 


RO ,ERDPB+Q. lOPL 


;Set address of message 
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TSTB 


(R0) + 


BNE 


10$ 


DEC 


RO 


SUB 


ERDPB+Q. IOPL,R0 


MOV 


RO,ERDPB+Q. IOPL+2 


DIR$ 


#ERDPB 


MOV 


#40, ERDPB+Q. IOPL+4 


RETURN 




.END 


XTREP 



;Null byte? 

;If NE, no - keep looking 
;Don't count null 
;Calculate length of string 
;Set length of string 
;Issue directive 

;Restore vertical format to normal 
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LAT Programming Facilities 



The Local Area Transport (LAT) communications protocol runs on terminal 
servers and host systems. It handles communications among local area network 
(LAN) devices attached to an Ethernet. Terminal servers are communications 
servers to which a number of devices, such as user terminals and printers, are 
attached. An application on a host node on the Ethernet can make logical connec- 
tions to these devices through the terminal server. During communication 
between the host node and remote device, the terminal server is almost transpar- 
ent. 

LAT software is available with DECnet-RSX-llM-PLUS and DECnet-Micro/ 
RSX. The LAT protocol and DECnet protocol are different, but they coexist on 
the same Ethernet. 

This chapter is written for programmers who are experienced in using RSX 
programming directives to write applications for directly-attached devices. The 
chapter describes how to write new applications or modify applications when the 
target device is not attached to the host, but to a remote terminal server else- 
where on the Ethernet. The chapter supplements the full-duplex terminal driver 
information in the RSX-1 IM/M-PLUS I/O Drivers Reference Manual or the 
Micro/RSX I/O Drivers Reference Manual. 

Throughout the chapter, "device" refers to a hardware terminal device. "Termi- 
nal" refers to the operating system's data structures for handling the hardware 
device. 

The chapter covers the following topics: 

■ Components of the LAT envirormient 

■ Programming steps for applications to LAT terminals 
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Directives for programming LAT terminals 



For a thorough introduction to the LAT environment, refer to the Local Area 
Transport (LAT) Network Concepts manual. 



6.1 Components of the LAT Environment 

The LAT environment consists of components on the terminal server and host, 
along with the Ethernet network that lets them communicate. Figure 6-1 illus- 
trates an application using a LAT connection. 

Figure 6-1 : Using a LAT Connection 




Figure 6-2 gives a more detailed picture of the components that make it possible 
for applications to communicate with remote LAT devices. 
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Figure 6-2: LAT Components for Applications 
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The terminal server is a piece of hardware that has a physical connection to the 
Ethernet. It also has connections to devices such as user terminals, printers, and 
so on. A device attached to the terminal server is the target of your application. 
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Note that LAT software exists on both the host and terminal server. The LAT pro- 
tocol is implemented on the host by the LAT process and on the terminal server 
by LAT server software. The LAT process on the host provides an interface 
between the terminal driver and Ethernet driver. It sends and receives messages 
having the LAT protocol. 

The LAT Control Program (LCP) is a network management interface to the LAT 
process and operating system. This chapter assumes that someone (called a "net- 
work manager") has responsibility for using LCP to set up the host LAT environ- 
ment. At your site, a system manager or programmer may perform the network 
manager function. The DECnet-RSX Guide to Network Management Utilities 
includes information on LCP. 

When a user and provider of LAT resources have a logical connection, a session 
exists. Applications can initiate sessions from the host to the terminal server, and 
interactive users can initiate sessions from the terminal server to the host. 

Each end point of the LAT session is a port. The figure shows ports on the RSX 
host that relate to local terminals (TT: devices) and ports on the terminal server to 
which user terminals and printers are attached. In order to perform I/O opera- 
tions on the device at the remote port, your application must make a connection 
between the local (host) port and the remote (terminal server) port. The next sec- 
tions describe the local port and remote port. 

6.1.1 The Local Port 

The local port on the RSX host is a LAT terminal. To create ports, the network 
manager uses LCP and creates a number of LAT terminals. LAT terminals are TT: 
devices for use only in LAT sessions. While other TT: devices perform I/O opera- 
tions to attached devices, the LAT terminals send and receive I/O across a net- 
work connection. Unlike other TT: devices, which are created by the SYSGEN 
procedure, LAT terminals are created after the SYSGEN and NETGEN procedures 
are complete. The numbering of the LAT terminals starts with the first available 
number after the numbers for hard-wired terminals, in octal notation. For exam- 
ple, if the system already has 7 terminals with the numbers zero (0) through 6, cre- 
ating 3 new LAT terminals creates TT7:, TTIO:, and TTll:. These terminals 
would have local port names of PORT_l , PORT_2, and PORT_3. 

A LAT terminal can be an interactive or application terminal. Interactive termi- 
nals are those that remote interactive users use to log on to the host. Application 
terminals are those that local applications use to connect to a remote device. 
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LCP normally creates LAT terminals as interactive terminals. Application termi- 
nals can be created in several ways. When initially creating LAT terminals, the 
network manager can specify a number to reserve for application use. Alterna- 
tively, after the LAT terminals exist, the network manager or an application can 
change an interactive terminal into an application terminal by specifying the tar- 
get information for the terminal. The target information comprises the name of a 
terminal server and a port and/or service on that terminal server to which any 
connect request that follows will be directed. 

To specify the target information and change an interactive terminal into an 
application terminal, the network manager issues the LCP SET PORT command. 
An application does this by issuing the Set Multiple Characteristics (SF.SMC) pro- 
gramming directive, including the appropriate characteristics (Section 6.3.4). 

Although the operating system communicates with a TT: device and the LAT pro- 
cess with a port, both refer to the same logical device, as Figure 6-3 illustrates. 
Figure 6-3 uses as examples the same TT: and port numbers as in Figure 6-2. 

Figure 6-3: The LAT Terminal and Local Port 



RSX 
OPERATING 
SYSTEM 

TT6: 



PORT 1 

X 

LAT 
PROCESS 
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The MCR command CON DISPLAY FOR *LH lists the LAT terminals on your host 
as TT: devices associated with the LH logical controller, as in the following exam- 
ple: 



The LCP SHOW PORT command lists your host's application terminals with the 
target information for each. It also lists the interactive terminals currently in use. 

6.1.2 The Remote Port 

The target for your application is a device at a remote port. The remote port is a 
physical outlet on the terminal server. Each terminal server has multiple ports. 
Input- or output-only devices, such as printers or badge readers, or standard 
input/output user terminals can be attached to terminal server ports. This chapter 
assumes that someone is responsible for the terminal server, and calls this person 
the "server manager." 

Terminal server ports have names. They can be default names or names that the 
terminal server manager created. To specify the target for your application, you 
can always choose to specify the name of the port to which the device is attached. 

On some terminal servers, the server manager can also designate a service name 
for one or more ports. A service is a resource such as a printer, card reader, or 
computer, that the terminal server makes available to network users. For exam- 
ple. Port 3 and Port 4 of the terminal server in Figure 6-2 could have the ser- 
vice name PRINTER. If the server manager assigns service names, an application 
can specify the target by its service name instead of its port. When the terminal 
server receives a request for a service, it passes the request to any free port that 
offers the service. This frees the application from dependence on a particular con- 
figuration at the terminal server; the terminal server manager can move and 
change devices without causing errors in applications. However, to ensure that 
the application connects to both a particular port and service, you can specify 
both a port and service name. 

For more information on setting up terminal servers, refer to the Local Area 
Transport (LAT) Network Concepts manual and the management guide for your 
terminal server. 



6-6 DECnet-RSX Programmer's Reference Manual 



TTll: 
TT12; 
TT13: 



LHAO 
LHAl 
LHA2 



6.2 LAT Application Programming 



This section describes the basic steps in writing a LAT application: 

1 . Coordinating available resources 

2 . Attaching the terminal 

3 . Setting the terminal characteristics 

4 . Establishing the connection 

5 . Performing read and write operations 

6. Terminating the connection 

6.2.1 Coordinating Available Resources 

Before writing your application, you need information about the resources avail- 
able at your site. If your site includes a terminal server manager and network man- 
ager, coordinating with them is important. They can ensure that your application 
gets the resources it needs and conforms to the existing LAT environment. 

First, you need information about the terminal server your application will 
access. The following list points out some questions to which you need answers. 
If your site has a terminal server manager, ask that person the questions in the first 
column; if not, enter the commands in the second column. 

Ask the server manager: Or enter this command : 

What is the terminal server name? SHOW SERVER 

What are the port names? SHOW PORT ALL 

What service names have been assigned? SHOW SERVICES/LOCAL 

This command gives a command syntax 
error if the terminal does not support ser- 
vice names. 

Next, find out what LAT terminals on the host are available for your application 
to use. If a system manager or network manager is available, ask what terminals 
you can use. If not, answer the questions in the first column of the following list 
by entering the commands in the second column of the list. 
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Ask the network manager: 



Or enter this command: 



What LAT terminals exist on the host? 



MCR command: 

CON DISPLAY ATTRIBUTES FOR *LH 



Which of the LAT terminals are in use 
by or reserved for other applications? 



LCP command: 

SHOW PORT/APPLICATION 



You and the network manager must decide whether to specify the application's 
target port and/or service from LCP, or through the application. 

Coordination with the network manager is important because LCP commands 
affect applications. For example: 

■ CREATE and START are required, before you run the application, to create 
the terminals and start the LAT process. Your network manager may also 
choose to reserve some terminals for applications at creation time. 

■ SET PORT lets the network manager specify the target for a LAT terminal, 
making that terminal an application terminal. Using LCP in this way readies 
the terminal for you and lets you omit a step in the application. 

■ DISCONNECT can terminate a connection. 

■ STOP halts the LAT process, aborting all LAT connections and destroying 
the target information for application terminals. 

For more information on LCP commands, refer to the DECnet-RSX Guide to Net- 
work Management Utilities. 

6.2.2 Attaching the Terminal 

Attaching the terminal ensures that your application gets exclusive use of the ter- 
minal and prevents it from receiving I/O requests from other applications. It is an 
optional step, but is very important and strongly recommended. If you omit this 
step, another application can attach the terminal, specify target information that 
overrides the information about your target, or perform other disruptive opera- 
tions. 

Attach the terminal by issuing an lO.ATT directive. 
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6.2.3 Setting the LAT Terminal Characteristics 

Next, specify the target terminal server port and/or service to which the terminal 
will later connect. The terminal server name, port name, and service name are the 
LAT terminal characteristics. Issue a Set Multiple Characteristics (SF.SMC) QIO, 
and specify these names by including the TC.MAP characteristics block. Section 
6.3.4.1 describes the TC.MAP characteristics block. 

Setting these characteristics sets the terminal nobroadcast (NOBRO) and slave 
characteristics. NOBRO prevents the terminal from receiving broadcasts; SLAVE 
prevents it from accepting unsolicited input. 

If the terminal is currently an interactive terminal, setting the characteristics to 
provide the target information changes it into an application terminal. If the ter- 
minal is currently an application terminal for which LCP previously specified a 
different target, your characteristics directive resets the characteristics to your 
target specifications. If the terminal is currently a reserved application terminal, it 
has no prior target information, but requires this information before you issue a 
connect request. 

You can set the characteristics only if the terminal is currently available for a ses- 
sion. If the terminal is engaged in a session on behalf of an interactive user or 
another application, the characteristics directive returns an error. 

You can omit setting the LAT characteristics in your application if your network 
manager has already used the LCP SET PORT command to do so. Using LCP in this 
way has some benefits; for example, it lets you designate a terminal for use by a 
specific application, whether or not the application is currently in use. Using LCP 
also allows you to use an existing application designed for a hard-wired device 
with a remote LAT device without modifying the application, as the next section 
explains. 

6.2.4 Establishing the Connection 

The application terminal establishes a network connection in order to exchange 
data with a remote LAT device. The LAT protocol includes a master/slave rela- 
tionship: terminal servers can establish sessions with hosts, but hosts cannot 
establish sessions with terminal servers. When your application initiates a con- 
nection, therefore, it actually sends a request soliciting the connection from the 
terminal server. You can request the connection explicitly or implicitly. 

An explicit connection starts when an application issues an Originate Explicit 
Connection (IO.ORG) directive. This directive solicits a connection between the 
application terminal and the terminal server specified in the Set Characteristics or 
LCP SET PORT operation. The IO.ORG directive is for LAT terminals only and is 
described in Section 6. 3. 2. 
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An implicit connection starts when an application immediately issues a Read Vir- 
tual Block (lO.RVB) or Write Virtual Block (lO.WVB) directive, instead of first 
requesting a connection. If the terminal is a LAT application terminal that is not 
yet connected to a remote terminal server, the initial read or write request starts a 
connection sequence. When the connection completes, the read or write opera- 
tion is performed. 

Implicit connections let you run an application originally written for a hard- 
wired device in a LAT environment. In most cases, you need not modify the appli- 
cation if you use LCP to specify the target for the application terminal. Note, how- 
ever, that the initial lO.RVB or lO.WVB directive will return status messages that 
report the success or failure of the connection attempt. Refer to Section 6.3.3 for 
the LAT connection status returns. 

Some target services, such as printers, have queues. If you make a connection 
request to a queued service, the connection does not complete until the service 
becomes available. To avoid an indefinite wait, include a time-out routine in your 
application. 

6.2.5 Reading and Writing Data 

The Read Virtual Block (lO.RVB) and Write Virtual Block (lO.WVB) QIO func- 
tions exchange data with the application terminal. Use them as you do for stan- 
dard terminals, but remember that if you have not created an explicit connection, 
the first read or write request establishes an implicit connection. Use time-out and 
error-handling routines with the first read or write request in case connection 
problems occur. 

6.2.6 Terminating the Connection 

Termination methods for explicit and implicit connections differ. 

An explicit connection terminates only in response to a Disconnect Terminal 
(lO.HNG) directive. lO.HNG assures a clean, synchronous termination and does 
not complete until the disconnect sequence completes. Once the directive com- 
pletes, the remote device becomes available for I/O from other sources. By not 
issuing an lO.HNG directive, an application that exits and restarts can maintain an 
available connection. 

Implicit connections terminate in response to both the lO.HNG and Detach I/O 
Device (lO.DET) directives and at task exit. Both lO.HNG and lO.DET assure 
clean, synchronous terminations and, on completion, leave the remote device 
available for I/O from other sources. Use lO.DET, however, only if you previ- 
ously attached the terminal. 
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Although task exit can terminate an implicit connection, avoid using it as a termi- 
nation method. If an application includes multiple tasks, the connection termi- 
nates when any one task exits, and the next read or write request establishes a 
new connection. Terminating and reconnecting consumes time and adds over- 
head. It can also cause you to lose the remote resource if another application is 
queued and waiting when yours disconnects. To avoid this, do one of the follow- 
ing: 

■ Modify the application to issue an lO . ORG directive . 

■ Create an initial task that issues an IO.ORG directive and then passes control 
to the existing application. 

Both lO.HNG and lO.DET allow the application terminal to send outstanding 
data to the terminal server before completing a disconnect request. 

Also note that any connection can terminate due to unexpected errors such as ter- 
minal server crash or network errors, or because the network manager has issued 
an LCP STOP or LCP TERMINATE command. 

6.2.7 Summary 

Table 6-1 summarizes the basic steps in a LAT application. The first column lists 
the functions to perform. The second and third columns show what you do to 
perform that function using explicit and implicit connections, respectively. 



Table 6-1 : Steps in a LAT Application 



Function 


Explicit Connection 


Implicit Connection 


Attach the 
terminal. 


Issue TO. ATT. 


Same. 


Set LAT terminal 
characteristics. 


Issue SF.SMC and include 
the TC.MAP characteristic. 
Alternatively, use the LCP 
SET PORT command prior 
to execution. 


Same. 


Establish a 
connection. 


Issue IO.ORG. 


Issue an initial lO.RVB or lO.WVB 
directive. 


Application executes. . . . 




Terminate the 
connection. 


Issue lO.HNG. 


Issue lO.HNG or lO.DET. (Use 
lO.DET only if you previously 
attached the terminal.) Task exit also 
terminates the connection. 
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6.3 Directives for Programming Application Terminals 



The LAT application terminals use standard RSX terminal driver directives. Table 
6-2 notes the special usage of directives that form important steps in a LAT appli- 
cation and gives the formats of those directives. 



Table 6-2: 


Terminal Driver Directive Usage for LAT Terminals 


Directive 


Use and Format 


lO.ATT 


Attarhfs thp tfrminal 




QIOW$ C lO . ATT , lun,efn , \pri] , [isb] , [ast] 


lO.DET 


Terminates an implicit connection to a LAT terminal that you previously 




attached. 




QIOW$C lO. DEr,lun,efn,{prq,[isb],[ast] 




1 criuiiiaics any coiiiicciioii lo jl i icruiiii<ii. 




QIOW$C lO.HNG, lun,efn,\pri\,[isb],[ast] 


IO.ORG 


Initiates an explicit connection between a LAT application terminal and 




the terminal server previously specified in an SF.SMC directive or LCP 




am rijKi commano. 




QIOW$C lO. ORG ,lun, efn , \pri] , [isb] , [ast] 


lO.RVB 


Reads data from a LAT application terminal. If the application terminal is 




not yet connected to the remote terminal server, this directive first cre- 




ates the connection and then performs the read operation. 




QIOW$C lO .R'VB,lun,efn,[prt],[isb],[asf], < stadd,size,pn > 


lO.WVB 


Writes data to a LAT application terminal. If the application terminal is 




not yet connected to the remote terminal server, this directive first cre- 




ates the connection and then performs the write operation. 




QIOW)i!C \0.^\B,lun,efn,[prt],[isb],[ast],<stadd,size,pn > 


SF.GMC 


Returns the name of the terminal server and port and/or service to which 




a LAT application terminal is mapped. Also returns the terminal's connec- 




tion status. 




QIOW$C SY.GMC,lun,efn,[prt],[isb],[ast],<stadd,size,pn > 


SF.SMC 


Maps the LAT application terminal to a specified terminal server port and/ 




or service to which it can later connect. 




QlOWjSC SY. sue, lun,efn,\pri],[isb],[asf],<stadd, size, pn > 
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The RSX-llM/M-PLUS I/O Drivers Reference Manual and Micro/RSX I/O 
Drivers Reference Manual have information on most of the directives you use. 
However, the following information applies only to LAT terminals: 

■ The IO.ORG directive. 

■ Status codes that result from connection solicitation requests. 

■ LAT-specific characteristics to use with Set Multiple Characteristics and Get 
Multiple Characteristics directives. 

6.3.1 Programming Suggestions 

The following suggestions may be helpful in writing your application: 

■ Use the Wait form of the QIO or an AST routine to synchronize the applica- 
tion with the completion of the connection. Using the Wait QIO form 
ensures that connection completes before the application proceeds. 

■ Check the status block after every read and write request. Because your con- 
nection to a LAT device is through the network, and not direct, check the 
status block to make sure that the write request succeeded. 

■ Remember in using all RSX directives that LAT devices are remote, not hard- 
wired. 

Occasionally, you might get a Device Not Ready (lE.DNR) error when attempting 
to perform a Read, Write, or Set Characteristics operation on a terminal that you 
have already attached successfully. This error can occur when a previous applica- 
tion has issued an lO.DET directive to terminate its connection. Upon receiving 
this directive, a terminal can detach and be ready for a new attachment even if the 
previous application's connection is completely terminated or its lO.DET direc- 
tive completed. In this case, your application can attach a terminal whose pre- 
vious session is not completely finished. To prevent your own application from 
causing this type of problem, issue an lO.HNG directive before each lO.DET. The 
lO.HNG cleanly breaks the connection before the lO.DET detaches the terminal. 
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I0.ORG 



I0.ORG 

(Originate Explicit Connection) 



6.3.2 iO.ORG — Originate Explicit Connection 

IO.ORG solicits a terminal server to initiate a connection to the LAT terminal. The 
directive does not complete until the connection is established or an error occurs. 
Ensure that the application waits for the connection by using the Wait QIO form 
or an AST routine. The LAT terminal characteristics must be set before you issue a 
connection request. 

IO.ORG is a control function; it does not cause any data transfer. 



QIO W$ C lO . ORG , lun.efn , \prq , [isb] , [ast] 
Parameters: 

The following are the IO.ORG parameters. For more information on QIO parame- 
ters, refer to the RSX-1 IM-PL US or Micro/RSX I/O Drivers Reference Manual. 

Parameter {Meaning 

lun The logical unit number associated with the physical device that the I/O 



Format: 



request accesses. 



efn 



The number of the event flag to associate with the QIO operation. An 
event flag is required with the Wait macro form. 



pri 



A priority value for compatibility with IAS. This parameter must have a 
value of zero (0) or null. 



isb 



The address of the I/O status block, a 2-word array that contains the com- 
pletion status for the I/O request on completion of the operation (see un- 
der "Status Returns"). 



ast 



The address of an optional user-written routine to execute after this call 
completes. When control branches to the specified address, it has the 
software priority of the requesting task. For no AST processing, omit the 
parameter or enter the value zero (0). 
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I0.ORG 



Status Returns: 

The I/O status block that isb specifies has the following format: 



1 



EXPLANATION CODE 



COMPLETION CODE 



LKG-1261-87 



The completion codes are described in the next section. 
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6.3.3 Status Codes for LAT Connections 



The following status codes result from the connection solicitation sequence. The 
sequence can be a result of an explicit (IO.ORG) or implicit (lO.RVB or lO.WVB) 
connection request. 



Symbol 
Name 


Decimal 
Value 


Octal 
Value 


Meaning 


IS.SUC 


1 


1 


Success. 


lE.RSU 


-17 


347 


Shared resource in use. The terminal is 
connected or busy with a connect request. 


lE.DNR 


-3 


375 


Device not ready. 


A status block that returns lE.DNR in the low byte returns one of the following 
in the high byte: 


Symbol 
Name 


Decimal 
Value 


Octal 
Value 


Meaning 










The terminal server or application termi- 
nal was unavailable or incorrectly speci- 
fied. 


lE.PRI 


-16 


360 


The terminal server's group access list 
does not include your host. 


lE.ICE 


-47 


321 


Internal corruption error. 


lE.NRJ 


-74 


266 


Service busy. 


lE.FLN 


-81 


251 


Terminal server service disabled. 


lE.CNR 


-96 


240 


Terminal not a LAT application terminal. 


lE.UKN 


-97 


237 


The specified terminal server port or ser- 
vice does not exist. 


lE.IRR 


-102 


232 


Insufficient resources at the terminal 



server. 

6.3.4 LAT Specific Characteristics for SF.GMC 

The Get Multiple Characteristics (SF.GMC) directive returns information about 
various characteristics. This section describes only the characteristics specific to 
LAT appHcation terminals: TC.MAP and TC.QDP. Using TC.MAP returns the 
application terminal's associated terminal server, remote port, and/or service 
name. Using TC.QDP returns the application terminal's connection status and 
queue position. Use this information in conjunction with the information on 
SF.GMC in the RSX-UM/M-PLUS or Micro/RSXI/O Drivers Reference Manual. 
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6.3.4.1 TC.MAP 

With the TC.MAP characteristic, the SF.GMC directive returns the name of a ter- 
minal server. It also returns either a service name or port name, or both. The 
block has the following format. 



LENGTH 



TC MAP 



SERVER NAME 
(16 BYTES) 



SERVICE NAME 
(16 BYTES) 



PORT NAME 
(16 BYTES) 



where 
Length 



is the length of the characteristics block. The length value 48. 
indicates the presence of characteristics data; indicates no 
data present. 
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Server name 



is the name of a terminal server, in up to 16. bytes, padded 
with zeroes. 



Service name is a service name, in up to 16. bytes, padded with zeroes. 

Either the service or port name must be present; both can be 
present. If no service name is returned, the first byte contains 
0. 



Port name is a port name, in up to 16. bytes, padded with zeroes. Either 

the service or port name must be present; both can be pre- 
sent. If no port name is returned, the first byte contains 0. 



The following programming fragment shows the format for setting up the 
TC.MAP characteristic to use with SF.GMC: 



CHRBUE: .BYTE IC.MAP ; Characteristic value 

.BYTE 48. ; Length of data buffer 

> 

SERVER: .BLKB 16. ; Returns the terminal server name. 

> 

SERVICE: .BLKB 16. ; Returns the service name 

; or zero (0) for no service name. 

> 

PORT: .BLKB 16. ; Returns the port name or 

; zero (0) for no port name. 

> 

CHRLEN=.- CHRBUE 



6.3.4.2 TC.QDP 

With the TC.QDP characteristic, SF.GMC returns the status of the connection re- 
quest. If the connection request is pending at a queued service, SF.GMC also re- 
turns the queue position. The block has the following format. 



STATUS 



TC.QDP 



LKG-1 263-87 
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where 



Status returns one of the following values: 

Not connected 

1 Connected 

< 1 Pending. A value greater than 1 indicates the request's position in 

the queue. 

6.3.5 LAT Specific Characteristics for SF.SI\/IC 

The Set Multiple Characteristics (SF.SMC) directive enables a task to set and reset 
the characteristics of a terminal. This section describes only the LAT characteris- 
tics. For information on other characteristics, refer to the RSX-1 IM/M-PLUS or 
Micro/RSX I/O Drivers Reference Manual. 

Using the TC.MAP characteristic, this directive supplies the information on the 
target terminal server port and/or service for the application terminal. Specifying 
the target of its future connection defines a terminal as an application terminal. 

Each SF.SMC directive resets the characteristics. The characteristics you specify 
supersede any previous settings, including those specified through LCP. 
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6.3.5.1 TC.MAP 

The TC.MAP characteristic specifies or clears the terminal server name and the 
port and/or service name. 

To set the LAT characteristics, enter 48. in the length field and include the termi- 
nal server name. Also specify the service name or port name, or both. To clear the 
LAT characteristics, enter in the length field. Clearing these characteristics re- 
turns an application terminal to its previous state as a reserved application termi- 
nal or an interactive terminal. 

The block has the following format. 



LENGTH 



TC MAP 



SERVER NAME 
(16 BYTES) 



SERVICE NAME 
(16 BYTES) 



PORT NAME 
(16 BYTES) 
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where 



Length 



is the characteristics block length. Use 48. to specify charac- 
teristics; use to clear characteristics. 



Server name 



is the name of the terminal server, in 16. or fewer bytes. End 
the name in a zero byte if it is smaller than 16. bytes. 



Service name 



is the name of a service that the terminal server offers. To 
omit the service name, allocate 16. bytes and enter in the 
first and last bytes of the field. End the name in a zero byte if it 
is smaller than 16. bytes. 



Port name 



is the name of a terminal server port. To omit the port name, 
allocate the full 16. bytes and enter in the first and last bytes 
of the field. End the name in a zero byte if it is smaller than 
16. bytes. 



Using this directive with TC.MAP to set LAT characteristics: 

■ Sets the specified terminal to SLAVE and NOBROADCAST . 

■ Sets the S6.LAT bit in unit status word 6 (U.TST6) in the Unit Control Block 
for the terminal. This bit indicates that the terminal is an application termi- 
nal. 

Using this directive with TC.MAP to clear characteristics returns the terminal to 
its previous state as a reserved application terminal or an interactive terminal 
available to interactive users or applications. If the terminal is connected, when 
you issue the directive, however, an lE.RSU error results. 

Status Returns: 

In addition to the standard SF.SMC status returns, lE.RSU applies only to LAT 
application terminals. 

Symbol Decimal Octal 

Name Value Value Meaning 

lE.RSU -17 357 Shared resource in use . The terminal is 



busy with another session or connection 
request. 
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The following fragment shows the format for setting up the TC.MAP characteris- 
tic: 



CHRBUF: .BYTE 
.BYTE 

> 

SERVER; .ASCIZ 
A=. -SERVER 

.BLKB 

> 

SERVICE: .ASCIZ 

B=.-SRVICE 

.BLKB 

J 

PORT: .ASCIZ 
C=.-PORT 

.BLKB 

> 

CHRLEN=. -CHRBUF 



TC.MAP 

/Server_name/ 
<16.-A> 

/Service_name/ 

<16.-B> 

/Port_name/ 

<16.-C> 



Characteristic value 
Length of data buffer 

Server name to 16. bytes 

Length of service name 

Pad with zeroes to 16. bytes) 

Service name to 16. bytes 
or zero (0) to omit name 
Length of service name 
Pad with zeroes to 16. bytes) 

Port name to 16. bytes 

or zero (0) to omit name 

Length of port name 

Pad with zeroes to 16. bytes. 



.4 LAT Application Programming Examples 

The following examples show how you can write to and read from a device 
attached to a remote terminal server. The first example, LATORG, uses the 
explicit connection method. The second example, LATEX, uses the implicit 
method. 
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6.4.1 Explicit Connection Example 



.TITLE LATORG 
.IDENT /Yl.O/ 



Copyright (C) 1983, 1985, 1986, 1987 by 
Digital Equipment Corporation, Maynard, Mass. 



This software is furnished under a license and may be used and copied 
only in accordance with the terms of such license and with the 
inclusion of the above copyright notice. This software or any other 
copies thereof may not be provided or otherwise made available to any 
other person. No title to and ownership of the software is hereby 
transferred . 

The information in this software is subject to change without notice 
and should not be construed as a commitment by Digital Equipment 
Corporat ion . 

Digital assumes no responsibility for the use or reliability of its 
software on equipment which is not supplied by Digital. 



This program demonstrates the use of LAT application terminals, 
using the explicit method for establishing the connection 
between the remote device and host terminal. 

First the program specifies the application terminal's target. 
Next, it issues an I0.ORG QIO to initiate an explicit connection. 

If the connection is successful, the program displays a message on the 
remote device and prompts the user for input. CTRL/Z terminates the 
sess ion . 

Data entered at the remote device is printed on the local TI:. 

The example uses TT30: as the host terminal. It writes data to a port 
named P0RT_2 on Terminal Server AUDIO. 

Assembly command: MAC LATORG , LATORG= LATORG 

To task build, enter the following command at the TKB> prompt: 

LATORG/PR : , LATORG= LATORG 
/ 

TASK= . . . LAT 
// 



.MCALL 



QIOW$ ,QIOW$C,ALUN$C,DIR$,EXIT$S 



START: ALUN$C 
QIOW$C 



1,TT,30 

10. ATT, 1,1, , 



lOSB 



; Assign LUN 1 to TT30: 
; Attach the terminal 
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5$ 



DIR$ 

BMI 

TSTB 

BPL 

MOV 

CALL 

JMP 



#SMC 
5$ 

lOSB 
10$ 

#SMCERR,RO 

ERROR 

EXIT 



Now, initiate the connection. 



10$: 

20$: 
30$: 



QIOW$C 

BMI 

TSTB 

BPL 

MOV 

CALL 

JMP 

MOV 

CALL 



I0.ORG, 1,1, 

20$ 

lOSB 

30$ 

#QIOERR,R0 

ERROR 

EXIT 

#SUCMSG,R0 
PRINT 



lOSB 



Specify the terminal's target 

If MI, directive error 

Check status 

If PL, continue 

Get error message text 

Call error routine 

Exit 



Initiate the connection 
If MI, directive error 
Check status 

If PL, connection OK - branch 
Get error message text 
Call error routine 
Exit 

Get success message text 
Print message 



Now the program reads data from the application terminal. The 
data is printed (displayed) on the local TI:. The program continues 
to read data from the terminal until the user at the remote device 
enters the terminating control sequence, CTRL/Z. 



35$; 



40$ 



50$ 



60$ 



EXIT; 



DIR$ 

BMI 

TSTB 

BPL 

CMPB 

BEQ 

MOV 

CALL 

BR 



#READ 
40$ 
lOSB 
50$ 

lOSB, #IE.EOF 
60$ 

#REAERR,R0 

ERROR 

EXIT 



MOV #INHEAD,WRITE5+Q. lOPL 

MOV IOSB+2 ,WRITE5+Q. IOPL+2 

ADD #8 . ,WRITE5+Q. IOPL+2 

DIR$ #WRITE5 

BR 35$ 

MOV #BYEMSG,WRITE5+Q. lOPL 

MOV #BYEMSL,WRITE5+Q. IOPL+2 

DIR$ #WRITE5 

QIOW$C I0.HNG,1,1 

QI0W$C I0.DET,1,1 
EXIT$S 



Read data from application terminal 

If MI, directive error 

Check status 

If PL, success - branch 

Did user type CTRL/Z? 

If EQ, yes - not an error 

Get error message text 

Call err9r routine 

And exit 

Move output buffer address to DPB 

Move the length of received data 

Add length of header 

Print the data 

Loop to read more data 

Move end message to DPB 
Move length of message 
Print terminating message 

Disconnect the session 
Detach the terminal 
And exit 



**-ERROR - Error handling routine. This routine formats an error 
message and prints it on the local TI: 



INPUTS: RO - Pointer to the error message text (must end in a byte) 



$DSW - Directive status from last directive executed 
lOSB - I/O status if $DSW is positive (no error) 

Registers altered: RO 
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ERROR: 



30$; 



EX: 



MOV 


R 1 _ / CP ) 


O Ol V C t\X 


CALL 


PRINT 




CLR 


Rl 




TSTB 






BPL 


30$ 


T'f Pf. no Hir'pr'+'i\7P Pr"T"or* 


MOV 


#DSWERR,RO 


Point at error text (DSW) 


CALL 


PRINT 


Print error message 


BISB 


Sn'^w Rl 




CALL 


v-v-/i^ V r\. 1 




BR 


P Y 

A 


OlcLildl LCJ L.UUUUU 11 C A i U 


MOV 




Point" ^t" mpc:c:3np i"pv1" 


CALL 


PRINT 


Print* Tn*^R mp«;c;janp /fir^t" h;^lf^ 


B I SB 


lOSB Rl 


Gpt" Tow hvi"p of TO^^R 


CALL 






MOV 


#I0SBM2 ,R0 


Point at 2nd half of lOSB message text 


CALL 


PRINT 


Print the message 


CLR 


Rl 


f^lp^T' Q't'Or'AOP 


BISB 






CALL 


CONVRT 


Convert and print 2nd half of lOSB 


MOV 


(SP)+,R1 


Restore register 


RETURN 




Back to caller 



**-CONVRT - Convert octal to ASCII and print it out 
INPUTS: Rl - Byte value to be converted 



All registers are preserved 



CONVRT : 


MOV 


R1,-(SP) 


Save Rl 




MOV 


R2,-(SP) 


Save R2 




MOV 


R3 ,-(SP) 


Save R3 




CLR 


R3 


Clear storage 




MOV 


#$TEMP+4 ,R2 


Point at temporary storage area 




CLRB 


-(R2) 


Ensure byte at the end 


10$: 


MOV 


Rl ,R3 


Get value to R3 




BIC 


#177770 ,R3 


Clear all but the last 3 bits 




ADD 


#60, R3 


Convert to ASCII 




MOVB 


R3,-(R2) 


Save ASCII in buffer 




CMP 


R2 ,#$TEMP 


Are we done? 




BEQ 


20$ 


If EQ, no 




ASR 


Rl 


Shift over 3 bits 




ASR 


Rl 


*•* * 




ASR 


Rl 


** * 




BR 


10$ 


Loop for more 


20$: 


MOV 


#$TEMP,R0 


Point at ASCII 




CALL 


PRINT 


• Print it out 




MOV 


(SP)+,R3 


• Restore registers 




MOV 


{SP)+,R2 


* * * 




MOV 


(SP)+,R1 


*** 




RETURN 




• Back to caller 



**-PRINT - Print a message on the local TI : 
INPUTS: RO - Address of string to print 

Note: The ASCII string must end in a byte 

All registers are preserved 
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PRINT: 


MOV 




CLR 


10$ : 


TSTB 




BEQ. 




INC 




BR 


20$: 


MOV 




MOV 




DIR$ 




MOV 




RETURN 


QIO: 


QIOW$ 


WRITE: 


QIOW$ 


WRITES : 


QIOW$ 


READ: 


QIOW$ 


SMC: 


QIOW$ 


CHRBUF: 


.BYTE 




.BYTE 


SERVER: 


.ASCIZ 


A=. -SERVER 




.BLKB 


SERVIC: 


.BYTE 




.BLKB 


PORT: 


.ASCIZ 


A= . -PORT 




.BLKB 


CHRLEN= 

/ 


.-CHRBUI 


9 

lOSB: 


.WORD 


$TEMP: 


.BLKB 


INHEAD: 


.ASCII 


INBUF: 


.BLKB 


INLEN=. 


-INBUF 


PROMPT : 


.ASCII 



RO,-(SP) 

-(SP) 

(R0) + 

20$ 

(SP) 

10$ 

(SP)+,QIO+Q. IOPL+2 
(SP) ,QIO+Q. lOPL 
#QIO 
(SP)+,R0 



Save pointer 

Clear storage 

Look for end 

If EQ, done 

Count a character 

Check next 

Move length to DPB 

Move address to DPB 

Print the message 

Restore pointer to message 

Back to caller 



I0.WVB,5,1, , , ,<0,0> 

lO.WVB, 1 , 1 , , lOSB, ,<0UTBUF,0UTLEN> 
I0.WVB,5,1, , , ,<0,0> 

10. RPR, 1 , 1 , , lOSB, ,< INBUF, INLEN, , PROMPT , PR0LEN> 
SF.SMC,1,1, ,IOSB, ,<CHRBUF,CHRLEN> ; DPB for SMC 



TC . MAP 
48. 

/AUDIO/ 
<16.-A> 


15. 

/P0RT_2/ 
<16.-A> 



0,0 
4 

<12><15>/DATA> / 
132. 



; Characteristic name 

; Characteristics buffer length 

; Server name (ends in byte) 

; Actual server name length 

; Allocate the full 16. bytes for name 

; Ensure byte (no service name) 
; Fill to 16. bytes 

; Port name 

; Length of actual port name 

; Allocate the full 16. bytes for port 

; Length of entire buffer 



lOSB for write and read operations 
Temporary storage for error routine 
Header for printing data to local TI 
Input buffer 



PROLEN= . -PROMPT 
.EVEN 

OUTBUF: .ASCII <12><15><7>/Application terminal now active/ 
OUTLEN= . -OUTBUF 

DSWERR: .ASCIZ <12><15>/Di rective Error code ($DSW) = / 
lOSBMl: .ASCIZ <12><15>/IOSB return code - Low byte = / 
I0SBM2: .^SCIZ / High byte = / 



SMCERR: 
QIOERR: 
SUCMSG: 
REAERR: 
BYEMSG: 

BYEMSL= 



.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCI I 

.ASCIZ 

-BYEMSG 

.EVEN 

.END 



<12><15>/Error setting terminal characteristics./ 
<12><15>/Error establ ishing impl ic i t connection./ 
<12><15>/Connect ion established to terminal server./ 
<12><15>/Er ror reading data from application terminal./ 
<12><15>/Read terminated by user. Now disconnecting/ 
/ application terminal./ 



START 
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6.4.2 Implicit Connection Example 



.TITLE LATEX 
.IDENT /Yl.O/ 



Copyright (C) 1983, 1985, 1986, 1987 by 
Digital Equipment Corporation, Maynard, Mass. 



This software is furnished under a license and may be used and copied 
only in accordance with the terms of such 1 i cense and with the 
inclusion of the above copyright notice. This software or any other 
copies thereof may not be provided or otherwise made available to any 
other person. No title to and ownership of the software is hereby 
transferred . 

The information in this software is subject to change without notice 
and should not be construed as a commitment by Digital Equipment 
Corporat ion . 

Digital assumes no responsibility for the use or reliability of its 
software on equipment which is not supplied by Digital. 



This program demonstrates the use of LAT application terminals, 
using the implicit method for establishing the connection 
between the host terminal and remote device. 

First the program specifies the target of the application terminal. 

Next, it posts a write request to the terminal to establish the 

connection. If the connection completes successfully, the program displays 

a message on the remote device and prompts the user for input. 

Any data that the user enters at the remote device is printed (displayed) 

on the local TI:. The user enters CTRL/Z to terminate the session. 

The example uses TT30: as the application terminal. It writes data to 
the port P0RT_2 on terminal server AUDIO. 

Assembly command: MAC LATEX , LATEX=LATEX 

To task build, enter the following command at the TKB> prompt: 

LATEX/PR: , LATEX=LATEX 
/ 

TASK=. . .LAT 

// 



.MCALL 



QIOW$,QIOW$C, ALUN$C,DIR$ ,EXIT$S 



START : 



ALUN$C 
QIOW$C 



1,TT, 30 

10. ATT, 1,1, , 



lOSB 



; Assign LLJN 1 to TT30: 
; Attach the terminal 



DIR$ 
BMI 



#SMC 
5$ 



Specify its target 

If MI, directive error 



(continued on next page) 



LAT Programming Facilities 



6-27 



5$: 



TSTB 

BPL 

MOV 

CALL 

JMP 



lOSB 
10$ 

#SMCERR,RO 

ERROR 

EXIT 



Check status 

If PL, continue 

Get error message text 

Call error routine 

And exit 



; Now, 


write data to the LAT application 


terminal and initiate 


; the 


implicit 


connection sequence. 




10$: 


DIR$ 


#WRITE 


Initiate connection and write data 




BMI 


20$ 


If MI, directive error 




TSTB 


lOSB 


Check completion status 




BPL 


30$ 


If PL, success - branch 


20$: 


MOV 


#QIOERR,R0 


Get error message text 




CALL 


ERROR 


Call error routine 




JMP 


EXIT 


And exit . . 


30$: 


MOV 


#SUCMSG,RO 


Get success message text 




CALL 


PRINT 


Print message 



Now the program reads data from the remote device. The data is 

printed on the local TI : . The program continues to read 

data until the user at the remote device enters the terminating 
control character sequence, CTRL/Z. 



35$: 



40$ 



50$ 



60$: 



DIR$ 


#READ 




Read data from remote device 


BMI 


40$ 




If MI, directive error 


TSTB 


lOSB 




Check status 


BPL 


50$ 




If PL, success - branch 


CMPB 


lOSB, #IE.EOF 




Did user type CTRL/Z? 


BEQ 


60$ 




If EQ, yes - not an error 


MOV 


#REAERR,RO 




Get error message text 


CALL 


ERROR 




Call error routine 


BR 


EXIT 




And exit 


MOV 


#INHEAD,WRITE5+Q 


. lOPL 


Move output buffer address to DPB 


MOV 


IOSB+2 ,WRITE5+Q. 


IOPL+2 


Move the length of received data 


ADD 


#8 . ,WRITE5+Q. IOPL+2 


Add length of header 


DIR$ 


#WRITE5 




Print the data 


BR 


35$ 




Loop to read more data 


MOV 


#BYEMSG,WRITE5+Q 


. lOPL 


Move end message to DPB 


MOV 


#BYEMSL,WRITE5+Q 


. IOPL+2 


• Move length of message 


DIR$ 


#WRITE5 




Print terminating message 



Now the program detaches the terminal. If the connection sequence 

was successful, the detach request terminates the connection. 

This is the recommended termination method for implicit connections 



EXIT; 



QIOW$C I0.DET,1,1 
EXIT$S 



Detach the terminal, disconnect 
And exit 



.SBTTL ERROR - Error handling routines 
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**-ERROR - Error handling routine. This routine formats an error 
message and prints it on the local TI: 

INPUTS: RO - Pointer to the error message text (must end in a byte) 
$DSW - Directive status from last directive executed 
lOSB - I/O status if $DSW is positive (no error) 

Registers altered: RO 



ERROR: 



30$ 



EX: 



MOV 


R1,-(SP) 


Save Rl 


CALL 


PRINT 


Print message 


CLR 


Rl 


Clear storage for error status 


TSTB 


$DSW 


Check for directive error 


BPL 


30$ 


If PL, no directive error 


MOV 


#DSWERR,RO 


Point at error text (DSW) 


CALL 


PRINT 


Print error message 


BISB 


$DSW, Rl 


Get error status to Rl 


CALL 


CONVRT 


Convert and print error message 


BR , 


EX 


Branch to common exit 


MOV 


#IOSBMl,R0 


Point at message text 


CALL 


PRINT 


Print lOSB message (first half) 


BISB 


I0SB,R1 


Get low byte of lOSB 


CALL 


CONVRT 


Convert and print low byte of lOSB 


MOV 


#I0SBM2 ,R0 


Point at 2nd half of lOSB message text 


CALL 


PRINT 


Print the message 


CLR 


Rl 


Clear storage 


BISB 


IOSB+1 ,R1 


Get value of 2nd half of lOSB 


CALL 


CONVRT 


■ Convert and print 2nd half of lOSB 


MOV 


(SP) + ,R1 


• Restore register 


RETURN 




Back to caller 



**-CONVRT - Convert octal to ASCII and print it out 
INPUTS: Rl - Byte value to convert 
All registers are preserved 



CONVRT : 


MOV 


Rl, -(SP) 


Save Rl 




MOV 


R2,-(SP) 


Save R2 




MOV 


R3,-(SP) 


Save R3 




CLR 


R3 


Clear storage 




MOV 


#$TEMP+4 ,R2 


Point at temporary storage area 




CLRB 


-(R2) 


Ensure byte at the end 


10$ : 


MOV 


Rl ,R3 


Get value to R3 




BIC 


#177770, R3 


Clear all but the last 3 bits 




ADD 


#60, R3 


• Convert to ASCII 




MOVB 


R3,-(R2) 


Save ASCII in buffer 




CMP 


R2 , #$TEMP 


• Are we done? 




BEQ 


20$ 


• If EQ, no 




ASR 


Rl 


• Shift over 3 bits 




ASR 


Rl 


. ** * 
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ASR 


Rl 




. *** 




BR 


10$ 




Loop for more 


t 

20$ : 


MOV 


#$TEMP,R0 




Point at ASCII 




CALL 


PRINT 




Print it 




MOV 


(SP)+,R3 




Restore registers 




MOV 


(SP)+,R2 




*** 




MOV 


(SP)+,R1 




*** 




RETURN 






Back to caller 


. **_ 


PRINT - Prints a message on the 


local TI: 


; INPUTS: RO - 


Address of string to 


pr int 




Note: 


The ASCII string must 


end 


in a byte 




All registers are preserved 






PRINT 


: MOV 


RO,-(SP) 




Save pointer 




CLR 


-(SP) 




Clear storage 


10$: 


TSTB 


(R0) + 




Look for end 




BEQ 


20$ 




If EQ, done 




INC 


(SP) 




Count a character 




BR 


10$ 




Check next 


2'0$: 


MOV 


(SP)+,QIO+Q. IOPL+2 




Move length to DPB 




MOV 


(SP) ,QIO+Q. lOPL 




Move address to DPB 




DIR$ 


#QIO 




Print the message 




MOV 


(SP)+,R0 




Restore pointer to message 




RETURN 






Back to caller 



.SBTTL DATA - Data areas, messages and DPBs 
**-DATA - Data areas, messages and DPBs 
Directive Parameter blocks (DPBs) 
QIO: QIOW$ I0.WVB,5,1, , , ,<0,0> 
WRITE: QIOW$ 10 . WVB , 1 , 1 , , lOSB , , <OUTBUF , OUTLEN> 
WRITES: QIOW$ lO.WVB, 5 , 1 , , , , <0 , 0> 

READ: QIOW$ 10. RPR, 1 , 1 ,, lOSB, ,<INBUF, INLEN, , PROMPT, PROLEN> 

Set characteristics DPB and characteristics buffer 
SMC: QIOW$ SF.SMC,1,1, ,IOSB, ,<CHRBUF,CHRLEN> ; DPB for SMC 



CHRBUF : . BYTE 
.BYTE 



TC . MAP 
48. 



; Characteristic name 

; Characteristics buffer length 
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SERVER: .ASCIZ /AUDIO/ 
A=. -SERVER 

.BLKB 



SERVIC: 



.BYTE 
.BLKB 



<16 .-A> 


15. 



PORT: .ASCIZ /P0RT_2/ 
A= . -PORT 

.BLKB 



<16.-A> 



CHRLEN= . -CHRBUF 



Data storage and ASCII Text 



0,0 
4 

<12><15>/DATA> / 
132. 



<12><15>/Enter data>/ 



lOSB: 


.WORD 


$TEMP: 


.BLKB 


INHEAD 


.ASCII 


INBUF: 


.BLKB 


INLEN= 


-INBUF 


PROMPT 


.ASCII 


PROLEN= 


= . -PROMPT 




.EVEN 


OUTBUF 


.ASCII 


OUTLEN= 


= . -OUTBUF 


DSWERR 


.ASCIZ 


lOSBMl 


.ASCIZ 


I0SBM2 


.ASCIZ 


SMCERR 


.ASCIZ 


QIOERR 


.ASCIZ 


SUCMSG 


.ASCIZ 


REAERR 


.ASCIZ 


BYEMSG 


.ASCII 




.ASCIZ 


BYEMSL= 


=. -BYEMSG 




.EVEN 




.END 



; Server name (ends in byte) 

; Actual server name length 

; Allocate the full 16. bytes for name 

; Ensure byte (no service name) 
; Fill to 16. bytes 

; Port name 

; Actual port name length 

; Allocate the full 16. bytes 

; Length of entire buffer 



lOSB for write and read operations 
Temporary storage for error routine 
Header for printing data to local TI 
Input buffer 



<12><15><7>/Appl icat ion terminal now active/ 

<12><15>/Directive Error code ($DSW) = / 
<12><15>/IOSB return code - Low byte = / 
/ High byte = / 

<12><15>/Error setting terminal characteristics./ 
<12><15>/Error establishing implicit connection./ 
<12><15>/Connect ion established to terminal server./ 
<12><15>/Error reading data from application terminal, 
<12><15>/Read terminated by user. Now disconnecting/ 
/ application terminal./ 



START 
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A 



Disconnect or Reject Reason Codes 



The following list contains the error reason codes available at the logical link user 
interface. These codes can be returned after either of the following events: 

■ The network rejected a connect request (lE.NRJ). 

■ The network aborted a connected logical link (NT .ABO). 

The symbols in column 1 are defined in the macro NSSYM$ . NSSYM$ is located in 
NETLIB.MLB (moved to LB:[1,1] during network generation). The events in col- 
umn 5 indicate the condition that occurred. C refers to a connect request and A 
refers to a network abort. 



Symbol 
Name 


Decimal 
Value 


Octal 
Value 


Standard Message/Explanation 


Event 


NE$RES 


1 


1 


Insufficient network resources 

The logical link could not be con- 
nected because either the local or the 
remote node had insufficient net- 
work resources (for example, insuffi- 
cient logical links, remote node 
counters, or dynamic storage region 
(DSR) on RSX systems). 


C 


NE$NOD 


2 


2 


Unrecognized node name 

The logical link could not be con- 
nected because the destination node 
name did not correspond to any 
known node address. 


C 
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Symbol Decimal Octal 

Name Value Value Standard Message/Explanation Event 



NE$NSR 


3 


3 


Remote node shutting down 

The logical link could not be con- 
nected because the network on the 
remote node was in the process of 
shiittinc down and would af cpnt no 
more logical link connections. 


C 


NE$UOB 


4 


4 


Unrecognized object 

The logical link could not be con- 

npptpd hppaiisp thf ohippt niimhpr or 

name specified did not exist at the 
remote node. 


C 


NE$FMT 


5 


5 


Invalid object name format 

The logical link could not be con- 

r%fcff^c\ hfr*^ni^f* fhf* fioHf HiH not" 

understand the object name format. 


C 


NE$MLB 


6 


6 


Object too busy 

The logical link could not be con- 
nected because the remote object 
was too busy handling other logical 
links. 


C 


NE$ABM 


8 


10 


Abort by network management 

The logical link has been aborted by 
an operator or a program using net- 
work mannopmpnt 

WV/X^ XXXAXXAIkV^XXXV^XXL . 


A 


NE$NNF 


10 


12 


Invalid node name format 

The logical link could not be con- 
nected because the remote node 
name format was invalid. For exam- 
ple, the name contained illegal char- 
acters or was too long. 


C 


NE$NSL 


11 


13 


Local node shutting down 

The logical link could not be con- 
nected because the network on the 
local node was in the process of shut- 
ting down. 


C 
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Symbol Decimal Octal 

Name Value Value Standard Message/Explanation Event 



NE$ACC 


34 


42 


Access control rejected 

The logical link could not be con- 
nected because the remote node or 
object could not understand or 
would not accept the access control 

llliUriiX<illLlli. 


C 


NE$ABO 


38 


46 


No response from object 

The logical link could not be con- 
nected because the object did not 
respond. For example, the object 
responded too slowly or terminated 
abnormally. 


C 


NE$ABO 


38 


46 


Remote node or object failed 

The connected logical link was 
aborted because the remote node or 
the object terminated abnormally. 


A 


NE$COM 


39 


47 


Node unreachable 

Either the logical link could not be 
connected or the connected logical 
link was aborted because no path 
existed to the remote node. 


C/A 
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B 

Object Types 



This appendix lists the object type code values defined by Digital, expressed as 
octal and decimal byte values. Digital reserves the right to add object types and to 
make changes to the descriptor formats used by the object types. At present, a 
descriptor format of 1 indicates a user process (object type 000). All other object 
types in the list have a descriptor format of 0, requiring definition by the object 
type codes in the first two columns. 



Object Type Process Type 

Octal Decimal 



000 


000 


General task, user process 


001 


001 


File Access Listener (FAL/DAP) Version 1 


002 


002 


Unit record services (URDS) 


003 


003 


Application terminal services (ATS) 


004 


004 


Command terminal services (CTS) 


005 


005 


RSX-1 IM Remote Task Control utility (TCL) Version 1 


006 


006 


Operator services interface 


007 


007 


Node resource manager 


010 


008 


IBM 3270-BSC Gateway 


Oil 


009 


IBM 2780-BSC Gateway 


012 


010 


IBM 3790-SDLC Gateway 


013 


Oil 


TPS application 


014 


012 


RT-1 1 DIBOL application 


015 


013 


TOPS-20 terminal handler 
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Object Type Process Type 



Octal 


Decimal 




016 


014 




TOPS-20 remote spooler 


017 


015 




RSX-1 IM Remote Task Control utility (TCL) Version 2 


020 


016 




TLK utility (LSN) 


021 


017 




File Access Listener (FAL/DAP) Version 4 and later 


022 


018 




RSX-1 IS Host Loader utility (HLD) 


023 


019 




Network Information and Control Exchange (NICE) 


024 


020 




RSTS/E media transfer program (NETCPY) 


025 


021 




RSTS/E-to-RSTS/E network command terminal handler 


026 


022 




Mail listener (DECnet-based electronic mail system) 


027 


023 




Network command terminal handler (host side) 


030 


024 




Network command terminal handler (terminal side) 


031 


025 




Loopback mirror (MIR) 


032 


026 




Event receiver (EVR) 


033 


027 




VAX A'^MS personal message utility 


034 


028 




File Transfer Spooler (FTS) 


035 


029 




PHONE utility 


036 


030 




Distributed data management facility (DDMF) 


037 


031 




X.25 Gateway access 


040-076 


032- 


-062 


Reserved for DECnet use 


077 


063 




DECnet test tool (DTR) 


100-177 


064- 


-127 


Reserved for DECnet use 


200-377 


128- 


-255 


Reserved for customer use 
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Remote File Access Error/Completion Codes 



0. 1 I/O Status Block Error Returns 

Each remote file access subroutine returns a 2 -word I/O status block. The con- 
tents of the second word depend on the contents of the first word. 

Table C- 1 describes each code that can be returned in the first word of the status 
block. The description of the code tells where to look up the description of the 
value returned in the second word. 



Table C-1 : First Word I/O Status Block Error Codes 



Error Code 


Description 


177777 (-1) 


Channel already active. 




An attempt was made to open a file on an active channel. Either 




use another channel or close the active channel before reusing it. 




The second word of the I/O status block is not applicable. 


177776 (-2) 


Channel not active 




A file operation request was made on an inactive channel. Either 




a file open was not issued on this channel or the network link for 




this channel was lost. 




The second word of the I/O status block is not applicable. 


177775 (-3) 


Data Access Protocol error 




An error was detected by the remote file system or by the remote 




server task. DAP then returns the error to the user. 




The second word of the I/O status block contains the file access 




error code. Look up this code in Table C-3. 


(continued on next page) 
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Table C-1 (Cont.)-' 


First Word I/O Status Block Error Codes 


Error Code 


Description 


17111 A (-4) 


NSP error (see Table C-2) 




The Data Access Protocol (DAP) utilities use Network Services 




Protocol (NSP) as a vehicle for accessing remote files. This code 




indicates that a problem was encountered at the NSP level. 




The low-order byte of the second word of the I/O status block 




contains one of the NSP error codes listed in Table C-2. If the 




error is network rejection (-7), the high-order byte of the second 




word of the I/O status block contains the reject reason code (see 




Appendix A). 


177773 (-5) 


Invalid attributes 




An invalid character was found in the attributes array (ichcir) of 




an open command. 


177772 (-6) 


Data ovprriiti 




The received message or block of messages did not fit into the 




user-specified buffer. 




The second word of the I/O status block contains the total num- 




ber of bytes read. 


17777 1 (-7) 


Tasks out of sync 




The requesting task and its server (FAL) have lost Data Access 




Protocol (DAP) message synchronization. This indicates a serious 




internal software problem to report to your system manager. 




The second word of the I/O status block is not applicable. 


177770 (-8) 


Invalid DAP channel (LUN) 




DAP channel numbers must fall in the range of 1 to 255- A value 




equal to zero (0) or greater than 255 is invalid. 




Thp second worrl of tVip T/O status hlof If is not annlirahle 


1111 bl (-9) 


Buffer allocation error for DAP channels 




TViprp is no morp hiiffpr snare availahip for thp DAP channpl ron- 




trol blocks. To extend the buffer size, rebuild the FORTRAN pro- 




gram, increasing the size of $FSR1 in the task build. 




The second word of the I/O status block is not applicable. 
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rirsi wora iiyj oiaius diock error uoucs 


Error Code 


Description 


177766 (-10.) 


Directive error 




Directive error from the executive. 




The second word of the I/O status block contains the DSW value. 


177765 (-11.) 


Illegal request 




An illegal request was made, such as an attempt to read from a 




file that was open for write. 




The second word of the I/O status block is not applicable. 
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Table C-2 contains the NSP error codes that pertain to the NSP error in Table C-1 
(177774). NSP error codes occupy the low-order byte of the second word of the 
I/O status block. With the exception of the network rejection (-7), the high-order 
byte is undefined. 



1 dUic v^"^. 




Error Code 


Description 


-1 


Required system resources are unavailable. 


-2 


A request was issued for a LUN on which there is no established logical 




link. 


-3 


The link was disconnected with the request outstanding. 


A 

— T 


The data message to be received was truncated because the receive 




buffer was too small. 


-5 


An argument specified in the call was incorrect. 


-6 


No network data was found in the user's mailbox. 


-7 


The network (NSP) rejected an attempted connect. The high-order 




byte contains the reject reason code (See Appendix A). 


Q 

— O 


A logical link has already been established on the LUN to which the 




user attempted to connect. 


-9 


The issuing task is not part of the network. OPNNT was never called. 


-10 


The user is attempting to access the network for a second time. 


-11 


An interrupt message transmission was attempted before the last one 




had finished. 


-12 


The user task to which the connection was attempted issued a connect 




reject. 


-13 


A buffer is outside the user address space or is not word aligned. 


-14 


The user is attempting to issue a GNDNT[W] when one is already pend- 




ing. 
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C.2 Data Access Protocol (DAP) Error Messages 



The DAP status code returns status from the remote file system or from the opera- 
tion of the cooperating process using DAP. The 2 -byte status field (16 bits) 
occupies the second word of the I/O status block and has two fields: 

■ Maccode (bits 12-15): Contains the error type code (see Table C-3 in 

Section C.2. 1) 

■ Miccode (bits 0-11): Contains the specified error reason code (see 

Tables C-4, C-5, and C-6, depending on error 
type, as described in Section C.2. 2) 

C.2.1 Maccode Field 

The maccode field is in the high-order byte of the second word in an I/O status 
block. The value returned in the maccode field describes the functional type of 
the error. The miccode field gives the specific reason for the error. The miccode 
field is the low-order byte of the same word that contains the maccode field. The 
last column of Table C-3 tells which table in this appendix contains the miccode 
values that correspond to the maccode values. 
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Table C-3: DAP Maccode Field Values 



Field 

Value 

(Octal) 


Error Type 


Meaning 


Miccode 
Table 





Pending 


The operation is in progress. 


E-3 


1 


Successful 


Returns information that indicates 
success. 


E-3 


2 


Unsupported 


This implementation of DAP does 
not support the specified request. 


E-2 


3 


Reserved 






4 


File open 


Errors that occur before a file is 
successfully opened. 


E-3 


5 


Transfer 
error 


Errors that occur after a file is 
opened and before it is closed. 


E-3 


6 


Transfer 
warning 


For operations on open files, indicates 
that the operation completed, but not 
with complete success. 


E-3 


7 


Access 
termination 


Errors associated with terminating 
access to a file. 


E-3 


10 


Format 


Error in parsing a message. Format 
is not correct. 


E-2 


11 


Invalid 


Field of message is invalid (that 
is, bits that are meant to be mutually 
exclusive are set, an undefined bit is 
set, a field value is out of range, or an 
illegal string is in a field.) 


E-2 


12 


Sync 


DAP message received out of 
synchronization. 


E-4 


13-15 


Reserved 






16-17 


User-defined status maccodes 
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C.2.2 Miccode Field 



The miccode field is located in the low-order byte of the second word in an I/O 
status block. The miccode field value identifies the specific reason for the 
maccode field error type (see Section C.2.1). Three different tables define the 
miccode field values, as follows: 

■ Table C-4: For use with maccode values 2, 10, 11 

■ Table C-5: For use with maccode values 0, 1, 4, 5, 6, 7 

■ Table C-6: For use with maccode value 1 2 

Table C-4 follows. The DAP message type number (column 1) is specified in bits 
6-11, and the DAP message field number (column 2) is specified in bits 0-5. The 
third column describes the field where the error is located. 

Table C-4: DAP Miccode Values for Use with Maccode Values of 2, 10, 
and 11 



Type Field 
Number Number 

(bits 6-11) (bits 0-5) Field Description 



Miscellaneous message errors 

00 00 Unspecified DAP message error 

1 DAP message type field (TYPE) error 

Configuration message errors 



00 


Unknown field 


10 


DAP message flags field (FLAGS) 


11 


Data stream identification field (STREAMID) 


12 


Length field (LENGTH) 


13 


Length extension field (LEN256) 


14 


BITCNT field (BITCNT) 


20 


Buffer size field (BUFSIZ) 


21 


Operating system type field (OSTYPE) 


22 


File system type field (FILESYS) 


23 


DAP version number (VERNUM) 


24 


ECO version number field (ECONUM) 


25 


USER protocol version number field (USRNUM) 


26 


DEC software release number field (DECVER) 


27 


User software release number field (USRVER) 


30 


System capabilities field (SYSCAP) 



(continued on next page) 
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Table C-4 (Cont.): DAP Miccode Values for Use with Maccode Values of 2, 
10, and 11 



Type Field 
Number Number 

(bits 6-1 1 ) (bits 0-5) Field Description 



Attributes message errors 





Unknown field 


1 f\ 


UAr message iiags iieia (^rLAocjj 


1 1 


Data stream identification (STREAMID) 


1 o 


Lengtn tieia (^LhiNvj i ri) 


1 X 


Length extension field (LEN 256) 




Dii count iiciu yoi i c^iM i ) 




i\tLlllJULC9 lliClIU llClVi \r\. 1 1 iVlI!,i>( U ^ 


9 1 


Uaxa. lype llclU yUA 1 A 1 I r E ) 




Field organization field (ORG) 


lo 


Kecora lormat iieia (^kjtjvi ) 




IVCCOrU <lliriUULC9 IICIU ^^IV^\ 1 ) 


9^ 


DIOCK Size IICIU ^^lJl-■C^ ) 


zo 


Maximum record size field (MRS) 


97 

Z / 


AllUCillUJIl L[U<lIl[liy IICIU ^^AlJV^^ 


30 


Bucket size field (BKS) 


31 


Fixed control area size field (FSZ) 


32 


Maximum record number field (MRN) 


33 


Run-time system field (RUNSYS) 


34 


Default extension quantity field (DEQ) 


35 


File options field (FOP) 


36 


Byte size field (BSZ) 


37 


Device characteristics field (DEV) 


40 


Spooling device characteristics field (SDC); reserved 


41 


Longest record length field (LRL) 


42 


Highest virtual block allocated field (HBK) 


43 


End-of-file block field (EBK) 


44 


First free byte field (FEB) 


45 


Starting LBN for contiguous file field (SBN) 
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Table C-4 (Cont.): DAP Miccode Values for Use with Maccode Values of 2, 
10, and 11 



Type Field 
Number Number 

(bits 6-1 1 ) (bits 0-5) Field Description 



Access message errors 



03 00 Unknown field 

1 DAP message flags field (FLAGS) 

1 1 Data stream identification field (STREAMID) 

1 2 Length field (LENGTH) 

1 3 Length extension field (LEN2 5 6) 

1 4 Bit count field (BITCNT) 

20 Access funcfion field (ACCFUNC) 

2 1 Access options field (ACCOPT) 

2 2 File specification field (FILESPEC) 

2 3 File access field (FAC) 

24 File-sharing field (SHR) 

2 5 Display attributes request field (DISPLAY) 

26 File password field (PASSWORD) 

Control message errors 

04 00 Unknown field 

1 DAP message flags field (FLAGS) 

1 1 Data stream identificafion field (STREAMID) 

1 2 Length field (LENGTH) 

1 3 Length extension field (LEN2 56) 

1 4 Bit count field (BITCNT) 

20 Control function field (CTLFUNC) 

2 1 Control menu field (CTLMENU) 

22 Record access field (RAC) 

23 Key field (KEY) 

2 4 Key of reference field (KRF) 

2 5 Record options field (ROP) 

26 Hash code field (HSH); reserved for future use 

27 Display attributes request field (DISPLAY) 
30 Block count (BLKCNT) 

Continue message errors 

05 00 Unknown field 

1 DAP message flags field (FLAGS) 

1 1 Data stream identification field (STREAMID) 

1 2 Length field (LENGTH) 

1 3 Length extension field (LEN2 5 6) 

1 4 Bit count field (BITCNT) 

20 Continue transfer funcdon field (CONFUNC) 
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Table C-4 (Cont.): DAP Miccode Values for Use with Maccode Values of 2, 
10, and 11 



Type Field 




Number Number 




(bits 6-1 1 ) (bits 0-5) 


Field Description 


Acknowledge message errors 




06 00 


Unknown field 


10 


DAP message flags field (FLAGS) 


11 


Data stream identification field (STREAMID) 


12 


Length field (LENGTH) 


13 


Length extension field (LEN256) 


14 


Bit count field (BITCNT) 


15 


System-specific field (SYSPEC) 


Access complete message errors 




07 00 


Unknown field 


10 


DAP message flags field (FLAGS) 


11 


Data stream identification field (STREAMID) 


12 


Length field (LENGTH) 


13 


Length extension field (LEN256) 


14 


Bit count field (BITCNT) 


20 


Access complete function field (CMPFUNC) 


21 


File options field (FOP) 


22 


Checksum field (CHECK) 


Key definition message errors 




12 00 


Unknown field 


10 


DAP message flags field (FLAGS) 


11 


Data stream identification field (STREAMID) 


12 


Length field (LENGTH) 


13 


Length extension field (LEN256) 


14 


Bit count field (BITCNT) 


20 


Key definition menu field (KEYMENU) 


21 


Key option flags field (FLG) 


22 


Data bucket fill quantity field (DFL) 


23 


Index bucket fill quantity field (IFL) 


24 


Key segment repeat count field (SEGCNT) 


25 


Key segment position field (POS) 


26 


Key segment size field (SIZ) 


27 


Key of reference field (REF) 


30 


Key name field (KNM) 
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Table C-4 (Cont.): DAP Miccode Values for Use with Maccode Values of 2, 
10, and 11 



TVDG 


Field 




Number 


Number 




(bits 6-11) 


(bits 0-5) 


Field Description 




31 


Null key character field (NUL) 




32 


Index area number field (IAN) 




33 


Lowest level area number field (LAN) 




34 


Data level area number field (DAN) 




35 


Key data type field (DTP) 




36 


Root VBN for this key field (RVB) 




37 


Hash algorithm value field (HAL) 




40 


First data bucket VBN field (DVB) 




41 


Data bucket size field (DBS) 




42 


Index bucket size field (IBS) 




43 


Level of root bucket field (LVL) 




44 


Total key size field (TKS) 




45 


Minimum record size field (MRL) 


Allocation message errors 




13 


00 


Unknown field 




10 


DAP message flags field (FLAGS) 




11 


Data stream identification field (STREAMID) 




12 


Length field (LENGTH) 




13 


Length extension field (LEN256) 




14 


Bit count field (BITCNT) 




20 


Allocation menu field (ALLMENU) 




21 


Relative volume number field (VOL) 




22 


Alignment options field (ALN) 




23 


Allocation options field (AOP) 




24 


Starting location field (LOG) 




25 


Related file identification field (RFI) 




26 


Allocation quantity field (ALQ) 




27 


Area identification field (AID) 




30 


Bucket size field (BKZ) 




31 


Default extension quantity field (DEQ) 



(continued on next page) 
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Table C-4 (Cont.): DAP Miccode Values for Use with Maccode Values of 2, 
10, and 11 



Type Field 
Number Number 

(bits 6-1 1 ) (bits 0-5) Field Description 



Summary message errors 



Date and time 
15 



00 


Unknown field 


1 r\ 


UAr message nags iieia (rLACjsj 


1 1 


Data stream laentiiication riela (a l KhAMlU) 


1 o 


Lengtn iieia (LhJNij in) 


1 '2 

13 


Length extension field (LEN256) 


1 /• 

14 


Bit count Iieia (Bi i CJN i ) 




nummary menu iieid (bUMiiJN U) 


21 


Number of keys field (NOK) 


22 


Number of areas field (NOA) 


23 


Number of record descriptors field (NOR) 


24 


Prologue version number (PVN) 


nessage errors 




00 


Unknown field 


10 


DAP message flags field (FLAGS) 


11 


Data stream identification field (STREAMID) 


12 


Length field (LENGTH) 


13 


Length extension field (LEN256) 


14 


Bit count field (BITCNT) 


20 


Date and time menu field (DATMENU) 


21 


Creation date and time field (CDT) 


22 


Last update date and time field (RDT) 


23 


Deletion date and time field (EDT) 


24 


Revision number field (RVN) 


25 


Backup date and time field (BDT) 


26 


Physical creation date and time field (PDT) 


27 


Accessed date and time field (ADT) 
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Table C-4 (Cont.): DAP Miccode Values for Use with Maccode Values of 2, 
10, and 11 



Type 
Number 
(bits 6-11) 



Field 
Number 
(bits 0-5) 



Field Description 



Protection message errors 

16 00 
10 
11 
12 
13 
14 
20 
21 
22 
23 
24 
25 

Name message errors 



17 



00 
10 

11 

12 
13 
14 
20 
21 



Unknown field 

DAP message flags field (FLAGS) 

Data stream identification field (STREAMID) 

Length field (LENGTH) 

Length extension field (LEN256) 

Bit count field (BITCNT) 

Protecdon menu field (PROTMENU) 

File owner field (OWNER) 

System protection field (PROTSYS) 

Owner protection field (PROTOWN) 

Group protection field (PROTGRP) 

World protecfion field (PROTWLD) 



Unknown field 

DAP message flags field (FLAGS) 

Data stream identification field (STREAMID) 

Length field (LENGTH) 

Length extension field (LEN256) 

Bit count field (BITCNT) 

Name type field (NAMETYPE) 

Name field (NAMESPEC) 



Access control list message errors (reserved for future use) 



20 



00 
10 
11 
12 
13 
14 
15 
20 
21 



Unknown field 

DAP message flags field (FLAGS) 

Data stream identification field (STREAMID) 

Length field (LENGTH) 

Length extension field (LEN256) 

Bit count field (BITCNT) 

System-specific field (SYSPEC) 

Access control list repeat count field (ACLCNT) 

Access control list entry field (ACL) 



Table C-5 follows. The error code number (column 1) is contained in bits 0-11. 
Symbolic status codes (column 2, when shown) refer to the corresponding RMS 
or FCS status codes. They are included here for ease of reference only, as they 
have no meaning for DAP. 
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Table C~5: DAP Miccode Values for Use with Maccode Values 0, 1 , 4, 5, 6, 7 



Error Code 
(bits 0-11) 


Symbolic 
Status Code 


Error Description 







Unspecified error 


1 


ER$ABO 


Operation aborted 


2 


ER$ACC 


Fl lACP could not access file 


3 


ER$ACT 


File activity precludes operation 


4 


ER$AID 


Bad area ID 


5 


ERSALN 


Alignment options error 


6 


ER$ALQ 


Allocation quantity too large or value 


7 


ER$ANI 


Not ANSI D format 


10 


ER$AOP 


Allocation options error 


11 


ER$AST 


Invalid (synchronous) operation at AST level 


12 


ER$ATR 


Attribute read error 


13 


ER$ATW 


Attribute write error 


14 


ER$BKS 


Bucket size too large 


15 


ER$BKZ 


Bucket size too large 


16 


ER$BLN 


BLN length error 


17 


ER$BOF 


Beginning of file detected 


20 


ER$BPA 


Private pool address 


21 


ER$BPS 


Private pool size 


22 


ER$BUG 


Internal RMS error condition detected 


23 


ER$CCR 


Cannot connect RAB 


24 


ER$CHG 


$ UPDATE changed a key without having 
attribute of XB$CHG set 


25 


ER$CHK 


Bucket format check-byte failure 


26 


ER$CLS 


RSTS/E close function failed 


27 


ER$COD 


Invalid or unsupported COD field 


30 


ER$CRE 


FllACP could not create file (STV = system- 
error-code) 
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Table C-5 (Cont.): DAP Miccode Values for Use with Maccode Values 0, 1 , 
4,5, 6,7 



Error Code 

/Kite n -fix 


Symbolic Status 
Code 


error uescripiion 


31 


ER$CUR 


No current record (operation not preceded 
by get/find) 


32 


ER$DAC 


Fl lACP deaccess error during close 


33 


ER$DAN 


Data area number invalid 


34 


ERSDEL 


RFA-accessed record was deleted 


35 


ERJitDEV 


Bad device, or inappropriate device type 


36 


ER$DIR 


Error in directory name 


37 


ER$DME 


Dynamic memory exhausted 


40 


ER$DNF 


Directory not found 


41 


ER$DNR 


Device not ready 


42 


ER$DPE 


Device has positioning error 


43 


ER$DTP 


DTP field invalid 


44 


ER$DUP 


Duplicate key detected; XB$DUP not set 


4S 


ERSENT 


Fl lACP enter function failed 


46 


ER$ENV 


Operation not selected in ORG$ macro 


47 


ER$EOF 


End of file 


50 


ER$ESS 


Expanded string area too short 


51 


ER$EXP 


File expiration date not yet reached 


52 


ER$EXT 


File extend failure 


53 


ER$FAB 


Not a vahd FAB (BID does not = FB$BID) 


54 


ER$FAC 


Illegal FAC for record operation, or FB$PUT 
not set for create 


55 


ER$FEX 


File already exists 


56 


ER$FID 


Invalid file ID 


57 


ER$FLG 


Invalid flag-bits combination 


60 


ER$FLK 


File is locked by other user 


61 


ER$FND 


Fl lACP find function failed 



(continued on next page) 
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Table C-5 (Cont.): DAP Miccode Values for Use with Maccode Values 0, 1 , 



4, 5,6,7 


Error Code 
(bits 0-11) 


Symbolic Status 
Code 


Error Description 


62 


ER$FNF 


File not found 


63 


ER$FNM 


Error in file name 


64 


ER$FOP 


Invalid file options 


65 


ER$FUL 


Device/file full 


66 


ER$IAN 


Index area number invalid 


67 


ER$IFI 


Invalid IFI value or unopened file 


70 


ER$IMX 


Maximum NUM (254) areas/key XABS 
exceeded 


71 


ER$INI 


$INIT macro never issued 


72 


ER^IOP 


Operation illegal or invalid for file organiza- 
tion 


73 


ER$IRC 


Illegal record encountered (with sequential 
files only) 


74 


ERSISI 


Invalid ISI value on unconnected RAB 


75 


ERIKBF 


Bad key buffer address (KBF = 0) 


76 


ER$KEY 


Invalid key field (KEY = or negative) 


77 


ER$KRF 


Invalid key of reference ($GET/$FIND) 


100 


ERIKSZ 


Key size too large 


101 


ER$LAN 


Lowest level index area number invalid 


102 


ER$LBL 


Not ANSI-labeled tape 


103 


ER$LBY 


Logical channel busy 


104 


ER$LCH 


Logical channel number too large 


105 


ER$LEX 


Logical extend error; prior extend still valid 


106 


ER$LOC 


LOG field invalid 


107 


ER$MAP 


Buffer-mapping error 


110 


ER$MKD 


Fl lACP could not mark file for deletion 


111 


ER$MRN 


MRN value = negative or relative key > MRN 
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Table C-5 (Cont.): DAP Miccode Values for Use with Maccode Values 0, 1 , 
4, 5, 6, 7 



Error Code 
(bits 0-11) 


Symbolic Status 
Code 


Error Description 


112 


ERjfMRS 


MRS value = for fixed length records and/ 
or relative files 


113 


ERSNAM 


NAM block address invalid (NAM = or is 
not accessible) 


114 


ER$NEF 


Not positioned to EOF (with sequential files 
only) 


115 


ER$NID 


Cannot allocate internal index descriptor 


116 


ER$NPK 


Indexed file; primary key defined 


117 


ER$OPN 


RSTS/E open function failed 


120 


ER$ORD 


XABs not in correct order 


121 


ER$ORG 


Invalid file organization value 


122 


ER$PLG 


Error in file's prologue (reconstruct file) 


123 


ER$POS 


POS field invalid (POS > MRS; STV = XAB 
indicator) 


124 


ER$PRM 


Bad file date field retrieved 


125 


ER$PRV 


Privilege violation (OS denies access) 


126 


ER$RAB 


Not a vahd RAB (BID does not = RB$BID) 


127 


ER$RAC 


Illegal RAC value 


130 


ER$RAT 


Illegal record attributes 


131 


ER$RBF 


Invalid record buffer address (either odd or 
not word aligned if BLK-IO) 


132 


ER$RER 


File read error 


133 


ER$REX 


Record already exists 


134 


ER$RFA 


Bad RFA value (RFA = 0) 


135 


ER$RFM 


Invalid record format 


136 


ER$RLK 


Target bucket locked by another stream 


137 


ER$RMV 


Fl lACP remove function failed 


140 


ER$RNF 


Record not found 
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Table C-5 (Cont.): DAP Miccode Values for Use with Maccode Values 0, 1 , 



4,5,6,7 

Error Code Symbolic Status 

(bits 0-1 1 ) Code Error Description 

141 ER$RNL Record not locked 

142 ER$ROP Invalid record options 

143 ER $ RPL Error while reading prologue 

144 ER$RRV Invalid RRV record encountered 

145 ER$RSA RAB stream currently active 

146 ER$RSZ Bad record size (RSZ > MRS or NOT = MRS 

if fixed length records) 

147 ERjfRTB Record too big for user's buffer 

150 ER$SEQ Primary key out of sequence (RAC = RB$SEQ 

for $PUT) 

1 5 1 ER$ SHR SHR field invalid for file (cannot share 

sequential files) 

152 ER$SIZ SIZ field invalid 

153 ER$ STK Stack too big for save area 

154 ERSiSSYS System directive error 

155 ER$TRE Index tree error 

1 56 ER$TYP Error in file type (extension on FNS is too big) 

157 ER$UBF lnvaliduserbufferaddress(0, odd, ornot 

word aligned if BLK-IO) 

160 ER$USZ Invalid user buffer size (USZ = 0) 

16 1 ER$VER Error in version number 

162 ERSVOL Invalid volume number 

163 ERSWER mie write error (STW = system-error-code) 

164 ERSWLK Device is write locked 

165 ERSWPL Error while writing prologue 

166 ER$XAB Not a valid XAB (@XAB = odd; STV = XAB 

indicator) 

167 BUGDDI Default directory invalid 
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Table C-5 (Cont.): DAP Miccode Values for Use with Maccode Values 0, 1 , 
4, 5,6,7 



Error Code 
(bits 0-11) 


Symbolic Status 
Code 


Error Description 


1 70 


CAA 




1/1 




VxHinoi ciooc iiic 


177 

1 / ^ 




UCllVCr A.O 1 


1 7^ 

1 / J 




i^Haiiiici (laaigniiicni idiiurc i v — byoKsin- 
error-code) 


174 


CNTRLO 


Terminal output ignored due to ( CTRL/O ) 


175 


CNTRLY 


Terminal input aborted due to ( CTRUY ) 


176 


DNA 


Default file name string address error 


177 


DVI 


Invalid device ID field 


200 


ESA 


Expanded string address error 


201 


FNA 


File name string address error 


202 


FSZ 


FSZ field invalid 


203 


lAL 


Invalid argument list 


204 


KFF 


Known file found 


205 


LNE 


Logical name error 


206 


NOD 


Node name error 


907 


IVrORMAI 


l_/pcr<l[IOIl aUCCcaslUl 


lift 
Z Ik) 


T\nt> 
L>K JJUr 


Inserted record had duplicate key 


'J 1 1 

£•11 


vjrv IIJA 


Index update error occurred; record inserted 


212 


r>K^ RT If 




91 ^ 


OK" PPV 
wrv IV i\ V 


ivccoru inscricu in prim<iry Key i» OKay , may 
not be accessible by secondary keys or RFA 


214 


CREATE 


File was created, but not opened 


215 


PBF 


Bad prompt buffer address 


216 


PNDING 


Asynchronous operation pending completion 


217 


QUO 


Quoted string error 


220 


RHB 


Record header buffer invalid 
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Table C-5 (Cont.): DAP Miccode Values for Use with Maccode Values 0, 1 , 
4, 5, 6, 7 



Error Code 
(bits 0-11) 


Symbolic Status 
Code 


Error Description 


221 


RLF 


Invalid related file 


222 


RSS 


Invalid resultant string size 


223 


RST 


Invalid resultant string address 


224 


SQO 


Operation not sequential 


225 


sue 


Operation successful 


226 


SPRSED 


Created file superseded existing version 


227 


SYN 


File name syntax error 


230 


TMO 


Timeout period expired 


231 


ER$BLK 


FB$BLK record attribute not supported 


232 


ER$BSZ 


Bad byte size 


233 


ER$CDR 


Cannot disconnect RAB 


234 


ER$CGJ 


Cannot get JFN for file 






Cannot open file 


Zoo 


UP <tTCM 


Bad JFN value 


Zj 1 




Cannot position to end of file 




HKJP 1 KU 


Cannot truncate file 


oA 1 

Z4 1 


HKJMJUr 


File currently in an undefined state; access is 
denied 


242 


ER$XCL 


File must be opened for exclusive access 


243 




Directory full 


244 


lE.HWR 


Handler not in system 


245 


lE.FHE 


Fatal hardware error 


246 




Attempt to write beyond EOF 


247 


lE.ONP 


Hardware option not present 


250 


lE.DNA 


Device not attached 


251 


lE.DAA 


Device already attached 
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Table C-5 (Cont.): DAP Miccode Values for Use with Maccode Values 0, 1 , 

4,5, 6,7 



Error Code 
(bits 0-11) 


Symbolic St3tus 
Code 


Error Description 


252 


IE. DUN 


Device not attachable 


253 


lE.RSU 


Shared resource in use 


254 


lE.OVR 


Illegal overlay request 


255 


lE.BCC 


Block check or CRC error 


256 


lE.NOD 


Caller's nodes exhausted 


257 


lE.IFU 


Index file full 


260 


lE.HFU 


File header full 


261 


lE.WAC 


Accessed for write 


262 


lE.CKS 


File header checksum failure 


263 


IE. WAT 


Attribute control list error 


264 


lE.ALN 


File already accessed on LUN 


265 


lE.BTF 


Bad tape format 


266 


lE.ILL 


Illegal operation on file descriptor block 


267 


IE.2DV 


Rename; two different devices 


270 


lE.FEX 


Rename; new file name already in use 


271 


lE.RNM 


Cannot rename old file system 


272 


IE. FOP 


File already open 


273 


lE.VER 


Parity error on device 


274 


lE.EOV 


End of volume detected 


275 


lE.DAO 


Data overrun 


276 


lE.BBE 


Bad block on device 


277 


IE. EOT 


End of tape detected 


300 


lE.NBF 


No buffer space for file 


301 


lE.NBK 


File exceeds allocated space; no blocks left 


302 


lE.NST 


Specified task not installed 


303 


lE.ULK 


Unlock error 


304 


lE.NLN 


No file accessed on LUN 
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Table C-5 (Cont.): DAP Miccode Values for Use with Maccode Values 0, 1 , 
4,5,6,7 



Error Code 
(bits 0-11) 


Symbolic Status 
Code 


Error Description 


305 


lE.SRE 


Send/receive failure 


306 


SPL 


Spool or submit command file failure 


307 


NMF 


No more files 


310 


CRC 


DAP file transfer checksum error 


311 




Quota exceeded 


312 


BUGDAP 


Internal network error condition detected 


313 


CNTRLC 


Terminal input aborted due to [CTRL/C ) 


314 


DFL 


Data bucket fill size > bucket size in XAB 


315 


ESL 


Invalid expanded string length 


316 


IBF 


Illegal bucket format 


317 


IBK 


Bucket size of LAN does not = IAN in XAB 


320 


IDX 


Index not initialized 


321 


IFA 


Illegal file attributes (corrupt file header) 


322 


IFL 


Index bucket fill size > bucket size in XAB 


323 


KNM 


Key name buffer cannot be read from or writ- 
ten to in XAB 


324 


KSI 


Index bucket will not hold two keys for key 
of reference 


325 


MBC 


Multibuffer count invalid (negative value) 


326 


NET 


Network operation failed at remote node 


327 


OK ALK 


Record is already locked 


330 


OK_DEL 


Deleted record successfully accessed 


331 


OK_LIM 


Retrieved record exceeds specified key value 


332 


OK NOP 


Key XAB not filled in 


333 


OK__RNF 


Nonexistent record successfully accessed 


334 


PLV 


Unsupported prologue version 


335 


REF 


Illegal key of reference in XAB 


336 


RSL 


Invalid resultant string length 


337 


RVU 


Error updating RRVs; some paths to data may 



be lost 
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Table C-5 (Cont.): DAP Miccode Values for Use with Maccode Values 0, 1 , 
4, 5, 6, 7 


Error Code 


Symbolic Status 


error uescripiion 


340 


SEG 


Data types other than string limited to one 
segment in XAB 


341 




Reserved 


342 


SUP 


Operation not supported over network 


343 


WBE 


Error on write behind 


344 


WLD 


Invalid wildcard operation 


j^j 


WSF 


AX/^ortinQ Qf*t full fc^nnr\t \r%c\c HiiffV*r^ in "wort- 

W UllVlil^ dC^l lUlX ICmIIIIV^L iUClV LfUlldd ill W yJL IV 

ing set) 


546 




Directory listing: error in reading volume set 


347 




Directory listing: error in reading file attri- 
butes 


350 




Directory listing: protection violation in try- 
ing to read the volume set, directory, or file 
name 


351 




Directory listing: protection violation in try- 
ing to read file attributes 


352 




Directory listing: file attributes do not exist 


353 




Directory listing: unable to recover directory 
list after continue transfer (skip) 


354 


SNE 


Sharing not enabled 


355 


SPE 


Sharing page count exceeded 


356 


UPI 


UPI bit not set when sharing with BRO set 


357 


ACS 


Error in access control string 


360 


TNS 


Terminator not seen 


361 


BES 


Bad escape sequence 


362 


PES 


Partial escape sequence 


363 


WCC 


Invalid wildcard context value 


364 


IDR 


Invalid directory rename operation 
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Table C-5 (Cont.): DAP Miccode Values for Use with Maccode Values 0, 1 , 
4, 5, 6, 7 


Error Code 
(bits 0-11) 


Symbolic Status 
Code 


Error Description 


365 


STR 


User structure (FAB/RAB) became invalid dur- 
ing operation 


366 


FTM 


Network file transfer mode precludes opera- 
tion 


6000 
to 

7777 




User-defined errors 







C-24 



DECnet-RSX Programmer's Reference Manual 



Table C-6 follows. The message type number is contained in bits 0-11. 
Table C-6: DAP Miccode Values for Use with Maccode Value 1 2 



Type Number 
(bits 0-11) 


Message Type 





Unknown message type 


1 


Configuration message 


2 


Attributes message 


3 


Access message 


4 


Control message 


5 


Continue transfer message 


6 


Acknowledge message 


7 


Access complete message 


10 


Data message 


11 


Status message 


12 


Key definition attributes extension message 


13 


Allocation attributes extension message 


14 


Summary attributes extension message 


15 


Date and time attributes extension message 


16 


Protection attributes extension message 


17 


Name message 


20 


Access control list extended attributes message 
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I 



D 

MACRO-1 1 Connect Block Offset and Code 

Definitions 



The following MACRO-1 1 offset and code definitions refer to connect block off- 
sets used in network connects and accepts. 



D-1 



.TITLE NETDEF - DECnet User Interface Definitions 
.IDENT /V02.05/ 

Copyright (C) 1978, 1979, 1980, 1987 by 
Digital Equipment Corporation, Maynard, Mass. 

Module Description: 

RSX-llM/S/M-PLUS Network Interface Offset and Error Definitions 

Macro to define DECnet MACRO user interface data structures 
and return values. 



.MACRO NETDF$,L,B 

.MCALL CRBDF$ 
CRBDF$ L,B 
.MCALL CNBDF$ 
CNBDF$ L,B 
.MCALL NSSYM$ 
NSSYM$ B 

.MACRO NETDF$,X,Y 
.ENDM NETDF$ 

.ENDM NETDF$ 

Request Descriptor Block offset definitions for connects. 

NOTE: Long connect block offsets are prefixed with M. 
Short connect block offsets are prefixed with N. 

The figure does not include the offset prefix. If you are using 
the long connect block, use M for the offset prefix. If you are 
using the short connect block, use N. 



; Request descriptor block 
; Request pending block 
; Return symbols 
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RND 



ROT 



.RFM 



FDRMRT 



(UNUSED) 



FDRMRT 1 
.RDEC 



-RDE 



FDRMRT 2 
.RGP 
.RU5 
-RNMC 



.RNM 



SHDRT LDNG 
CONNECT CONNECT 
BLOCK BLOCK 



000 
004 

00G 



010 
030 

010 
012 
030 

010 
012 
014 
01G 
030 



000 
004 

00G 



010 
030 

010 
012 
030 

010 
012 
014 
01G 
030 



.RIDC 



,RID 



.RPSC 



.RPS 



.RRCC 



.RRC 



032 
034 
052 
054 
05G 
0G4 
0GG 
070 
10G 



032 
034 
102 
104 
10G 
154 
15G 
1G0 
230 
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.MACRO CRBDF$,L,B,LST 
.ilf nb LST .List 
.ASECT 

Long connect block offsets (support for long passwords, user names and 
accounting information) 



.=0 










M.RND: 


L' 


.BLKB 


6 ; 


Destination node name 


M.RFM: 


L' 


.BLKB 


1 ; 


Destination descriptor format 


M.ROT: 


L' 


.BLKB 


1 


Destination object type 




















Format - 




.BLKB 18. 


; [UNUSED] 












.=.-18 








Format 1 - 


M.RDEC 


'L 


.BLKW 


1 ; 


Destination process byte count 


M.RDE: 


L' 


.BLKB 


16. ; 


Destination process 












; Offsets 


between N.RND 


and N.RDE and M.RND and M.RDE for format 1 or N. 


; and M.RGP for format 


2 must be identical in both the short and long 


; connect 


blocks. Do not add an 


offset to one without adding it to the 


.=.-18 






> 


Format 2 - 


M.RGP: 


L' 


.BLKW 


1 ; 


Destination group 


M.RUS: 


L' 


.BLKW 


1 ; 


Destination user 


M.RNMC 


'L 


.BLKW 


1 ; 


Destination name byte count 


M.RNM: 


L' 


.BLKB 


12. ; 


Destination name 












M.RIDC 


•L 


.BLKW 


1 


Requesting process ID byte count 


M.RID: 


L' 


.BLKB 


40. ; 


Requesting process ID 


M.RPSC 


•L 


.BLKW 


1 ; 


Requesting password byte count 


M.RPS: 


'L' 


.BLKB 


40. ; 


Requesting password byte count 


M.RACG 


: 'L 


.BLKW 


1 ; 


Accounting information byte count 


M.RAG: 


•L' 


.BLKB 


40. ; 


Accounting information 


M.RQL= 


•B' 


-M.RND 


\ 


Length of RDB 



Short connect block offsets. Included for compatibility with 
existing software and versions of DECnet RSX 
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,=0 

N.RND: 'L' .BLKB 

N.RFMr'L' .BLKB 

N.ROT: 'L' .BLKB 



6 ; Destination 
1 ; Destination 
1 ; Destination 



node name 
descriptor format 
object type 



.BLKB 18, 



.=.-18. 

N.RDEC: 'L' 
N.RDE: 'L' 



[UNUSED] 



Format 



.BLKW 
.BLKB 



1 

16. 



Format 1 - 
; Destination process byte count 
; Destination process 



Offsets between N.RND and N.RDE and M.RND and M.RDE for format 1 or N.RGP 
and M.RGP for format 2 must be identical in both the short and long 
connect blocks. Do not add an offset to one without adding it to the other. 



.=.-18 






> 


Format 2 - 


N.RGP: 


L' 


.BLKW 


1 


Destination group 


N.RUS: 


L' 


.BLKW 


1 


Destination user 


N.RNMC 


'L' 


.BLKW 


1 


Destination name byte count 


N.RNM: 


L' 


.BLKB 


12. 


Destination name 










N.RIDC 


•L' 


.BLKW 


1 


Requesting process ID byte count 


N.RID: 


L' 


.BLKB 


16. 


Requesting process id 


N.RPSG 


'L' 


.BLKW 


1 


, Requesting password byte count 


N.RPS: 


L' 


.BLKB 


8. 


Requesting password 


N.RACC 


'L' 


.BLKW 


1 


; Accounting information byte count 


N.RAC: 


L' 


.BLKB 


16. 


, Accounting information 


N.RQL= 


B'. 


-N.RND 


J 


; Length of short RDB 



.PSECT 

.if nb LST 

.Nlist 

.iff 

.MACRO CRBDF$,X,Y,Z 
.ENDM CRBDF$ 
.endc 

.ENDM CRBDF$ 

Connect Block offset definitions for received connect requests. 

NOTE: Long connect block offsets are prefixed with M (example: M.RND) 
Short connect block offsets are prefixed with N. 



The offset prefix is not included in the diagram. If you are using 
the long connect block, use M for the offset prefix. If you are 
using the short connect block, use N. 
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DDT 



,CTL 



5EGZ 



.DFM 



SHDRT 
CONNECT 
BLDCK 
000 

002 

005/004 



LONG 
CONNECT 
BLOCK 
000 

002 

005/004 



FORMFIT 




FORMRT 1 




FORMRT 2 



.DUS 



.DNMC 



.DNM 



006 
026 



006 

010 
026 



006 
010 
012 
014 

026 



006 
026 



006 

010 

026 

006 

010 

012 
014 

026 
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.MACRO CNBDF$,L,B,LST 
.iif nb LST .List 
.ASECT 



Incoming short connect block offsets 



.=0 

M.CTL: 



.BLKW 



M.SEGZ:'L' .BLKW 
M.DFMr'L' .BLKB 
M.DOT:'L' .BLKB 



1 ; Temporary link address 
J 

1 ; Segment size 

1 ; Destination descriptor format 

1 ; Destination object type 



• BLKB 



18. 



.=.-18. 

M.DDEC: 'L' 
M.DDEr'L' 

.=.-18. 

M.DGP:'L' 
M.DUS: 'L' 
M.DNMC: 'L' 
M.DNM: 'L' 



.BLKW 
• BLKB 



.BLKW 
.BLKW 
.BLKW 
.BLKB 



Format 
[UNUSED] 



1 

16. 



Format 1 - 

; Destination process byte count 
; Destination process 



1 
1 
1 

12. 



Format 2 - 
Destination group 
Destination user 
Destination name byte count 
Destination name 



M.SND: 'L' 
M.SFM: 'L' 
M.SOT: 'L' 



•BLKB 6 ; Source node name 

.BLKB 1 ; Source descriptor format 

.BLKB 1 ; Source object type 



.BLKB 



18. 



.=.-18. 

M.SDEC: 'L' 
M.SDE: 'L' 

.=.-18. 

M.SGP: 'L' 
M.SUS: 'L' 
M.SNMC: 'L' 
M.SNM: 'L' 



.BLKW 
.BLKB 



.BLKW 
.BLKW 
.BLKW 
.BLKB 



Format - 
[UNUSED] 

Format 1 - 
1 ; Source process name byte count 
16. ; Source process name 

; Format 2 - 

1 ; Source group 

1 ; Source user 

1 ; Source name byte count 

12. ; Source name 
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$$$=. 

M.CIDC:'L' .BLKW 1 

M.CID:'L' .BLKB ^0. 

M.CPSC:'L' .BLKW 1 

M.CPS:'L' .BLKB -40. 

M.CACCr'L' .BLKW 1 

M.CACr'L' .BLKB 40. 

M.CDAC:'L' .BLKW 1 
M.CDA: 'L' 



M.CBL='B' .-M.CTL 



; Source task ID byte count 

; Source task ID 

; Password byte count 

; Password 

; Accounting information byte count 

; Accounting information 

; Optional data byte count 

; Optional data buffer 

; Length of CNB (without any data) 



CDEV:'L' .BLKW 
CUNI:'L' .BLKB 

.EVEN 
CUICr'L' .BLKW 
CDDS.-'L' .BLKB 



1 ; Default device name (from account file) 

1 ; Default device unit number 

1 ; Login UIC from account file 

11. ; Default directory string (byte 0=0 => none) 



Incoming short connect block offsets 



=0 

.CTL: 



.BLKW 



Temporary link address 



N.SEGZ:'L' .BLKW 1 ; Segment size 

N.DFM:'L' .BLKB 1 ; Destination descriptor format 

N.DOT:'L' .BLKB 1 ; Destination object type 



,BLKB 



18. 



.=.-18. 

N.DDEG: 'L' 
N.DDE: 'L' 

.=.-18. 

N.DGP: 'L' 
N.DUS: 'L' 
N.DNMC: 'L' 
N.DNM: 'L' 



.BLKW 
.BLKB 



.BLKW 
.BLKW 
.BLKW 
.BLKB 



Format - 
[UNUSED] 

Format 1 - 

Destination process byte count 
Destination process 



1 

16. 



1 
1 
1 

12. 



Format 2 - 

Destination group 
Destination user 
Destination name byte count 
Destination name 



N.SND:'L' .BLKB 
N.SFM:'L' .BLKB 
N.SOT: 'L' .BLKB 



6 ; Source 
1 ; Source 
1 ; Source 



node name 
descriptor format 
object type 
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.BLKB 18. 

.=.-18. 

N.SDEC;'L' .BLKW 

N.SDE:'L' .BLKB 

.=.-18. 

N.SGPr'L' .BLKW 

N.SUS:'L' .BLKW 

N.SNMCr'L' .BLKW 

N.SNMr'L' .BLKB 



$$$=. 

N.CIDC:'L' .BLKW 

N.CID:'L' .BLKB 

N.CPSC:'L' .BLKW 

N.CPSr'L' .BLKB 

N.CACC:'L' .BLKW 

N.CAC:'L' .BLKB 

N.CDAC:'L' .BLKW 
N.CDA: 'L' 

N.CBL='B' .-N.CTL 

.=$$$ 

N.CDEV:'L' .BLKW 
N.CUNI:'L' .BLKB 

.EVEN 
N.CUICi'L' .BLKW 
N.CDDS:'L' .BLKB 

.PSECT 

.ENDM CNBDF$ 



Format - 
[UNUSED] 

Format 1 - 
1 ; Source process name byte count 
16. ; Source process name 



1 
1 
1 

12. 



Format 2 - 
Source group 
Source user 
Source name byte count 
Source name 



1 ; Source task ID byte count 

16. ; Source task ID 

1 ; Password byte count 

8. ; Password 

1 ; Accounting information byte count 

16. ; Accounting information 

1 ; Optional data byte count 

; Optional data buffer 



Length of CNB (without any data) 



1 ; Default device name (from account file) 

1 ; Default device unit number 

I ; Login UIC from account file 

II ; Default directory string (byte 0=0 => none) 
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E 

Network Error/Completion Codes for 
FORTRAN, COBOL, and BASIC-PLUS-2 



This appendix lists tlie error/completion codes that can be returned in the first 
word of any 2-word I/O status block by certain calls in the FORTRAN, COBOL, 
and BASIC-PLUS-2 languages. 

1 The request was successful. 

2 The request was successful, but some optional data was lost. 
- 1 Required system resources are not available. 

-2 A request was issued for a LUN on which there is no established logical 
link. 

-3 The link was disconnected with the request outstanding. 

-4 The data received was truncated because the receive buffer was too 
small. 

-5 An argument specified in the call is incorrect. 

-6 No network data was found in the user's network data queue. 

-7 The network (NSP) rejected an attempted connect. 

-8 A logical link has already been established on the LUN to which the 
user attempted to connect. 

-9 The issuing task is not part of the network (that is, OPNNT was never 
called). 
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-10 The user is attempting to access the network for a second time. 

-11 Transmission of an interrupt message was attempted before the last one 
finished. 

-12 A connect reject was issued by the user task to which the connection 
was attempted. 

-13 A buffer either is outside the user address space or is not word aligned. 

-14 The user is attempting to issue a GNDNT[W] when one is already pend- 
ing. 

-20 A RUNNCW was issued for which there was not enough dynamic mem- 
ory on the remote node. 

-21 A RUNNCW or ABONC W was issued for a task that was not installed on 
the remote node. 

-22 A RUNNCW was issued with an invalid time parameter. 

-23 Either an ABONC W was issued for a task that was not active, or a 

RUNNCW without scheduling parameters was issued for a task that 
already is active. 

-24 There was a privilege violation on an RUNNCW or ABONCW attempt. 

-25 An ABONCW was issued for a task that either was being loaded into or 
was exiting from the remote node. 

-26 An RUNNCW was issued with an invalid UlC . 

-40 A directive error; the second word of the status block contains the 
actual directive error code. 
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Network MACRO-11 Error/Completion 

Codes 



Applicable Standard RSX Codes 

The following MACRO-11 error completion codes include all network related 
I/O error completion codes for this manual. These codes are defined in the 
IOERR$ macro in RSXMAC.SML, which is referenced in the NSSYM$ macro in 
NETLIB.MLB. 



Symbol 
Name 


Decimal 
Value 


Octal 
Value 


Meaning 


IS. sue 


1 


1 


The request was successful. 


IS.DAO 


2 


2 


The request was successful, but some 
data was lost. 


lE.BAD 


-1 


377 


Invalid buffer parameter, or data length 
exceeds 16. bytes. 


IE. SPG 


-6 


372 


Invalid buffer parameters: the buffer 
may not be word-aligned, may be out- 
side user address space, or may exceed 
8128. bytes. 


lE.WLK 


-12 


364 


Transmission of an interrupt message 
was attempted before the last one fin- 
ished. 


lE.DAO 


-13 


363 


Data overrun; unstored data was lost. 


lE.ABO 


-15 


361 


The link was aborted or disconnected 
(see disconnect and reject reason 
codes. Appendix A). 
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oyrnDOi 
Name 


uecirnai 
Value 


\JC\ai 

Value 


Meaning 


lE.PRI 


-16 


360 


The network is not accessed on this 
LUN. 


lE.RSU 


-17 


357 


Required system resources are not 
available. 


lE.ALN 


-34 


336 


The specified LUN is already estab- 
lished. 


lE.NLN 


-37 


333 


There is no established logical link on 
the specified LUN. 


lE.URJ 


-73 


267 


The remote task rejected an attempted 
connection. 


lE.NRJ 


-74 


266 


The network rejected an attempted 
connection (see disconnect and reject 
reason codes, Appendix A). 


lE.NDA 


-78 


262 


There is no data to return. 


lE.NNT 


-94 


242 


The issuing task is not a network task; 
OPN$ was not executed successfully. 
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Values for Ethernet and 802.3 Addressing 



This appendix provides information on assigned values for 

■ Multicast addresses 

■ Protocol types for Ethernet format 

■ Service Access Point (SAP) addresses for 802 . 3 format 

■ Subnetwork Access Protocol (SNAP) identifiers for 802 . 3 format 

All values are in hexadecimal notation, with nn representing variables in 
addresses and protocols. 

Note that the protocols and addresses for customer use will not change, but the 
assigned cross-company and internal Digital values may increase beyond the list 
in this appendix. The IEEE is continuing to assign SAP and SNAP values; the 802.3 
information is currently valid but is still changing. 

While this appendix includes the assigned multicast and SAP values for broad- 
casts, you should avoid using them, since broadcasting congests the network. 



G.I Multicast Addresses 

Multicast addresses in the following format are reserved for Digital Equipment 
Corporation customer use: 

AB-OO-04-OO-ww-ww 



G-1 



All companies can use the following reserved multicast addresses-. 



Value 



Meaning 



FF-FF-FF-FF-FF-FF 



Broadcast 



CF-00-00-00-00-00 



Loopback assistance 



Digital Equipment Corporation reserves the following ranges for internal use 
only: 

08- 00-2B-nn-nn-nn 

09- 00-2B-nn-nn-nn 

AA-OO-OO-nn-nn-nn 
AA-00-0 1 -nn-nn-nn 
AA-OO-02-nn-nn-nn 
AA-OO-O^-nn-nn-nn 
AA-00-04-nn-nn-nn 

AB-00-00-0 1 -00-00 
AB-00-00-02-00-00 
AB-00-00-03-00-00 
AB-00-00-04-00-00 

AB-00-04-0 1 -nn-nn 

In a Digital-only environment, you can use any values that fall outside of the 
Digital Equipment Corporation ranges. In a multi- vendor environment, however, 
these values might conflict with the system software of the other vendors. 
Addresses in the Digital customer range, in contrast, are reserved; they will not 
conflict even in a multi- vendor environment. 

.1.1 Ethernet Protocol Types 

The following protocol type is reserved for Digital Equipment Corporation cus- 
tomer use: 

60-06 

All companies using the Ethernet protocol use the following protocol type: 
Value Meaning 
90-00 Loopback 
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Digital Equipment Corporation reserves protocol types in the following ranges 
for internal use only: 

60-00 to 60-05 

60-07 to 60-09 

80-38 to 80-42 

In a Digital-only environment, you can use values outside of the Digital 
Equipment Corporation range. In a multi- vendor environment, however, using 
other values could cause conflicts with other vendors' software. 

Values in the range 00-00 through 05-DC are reserved for internal use and will 
cause data link level errors in an application. 

G.2 SAP Addresses 

The IEEE has not yet assigned SAPs to Digital Equipment Corporation, but it has 
assigned the following for inter-company use: 



Value Name/Meaning 

00 The null SAP: addresses just the data link layer, as in an XID or a TEST mes- 

sage. 

02 The logical link control sub-layer management function individual SAP: 
addresses an individual network management entity on the system. 

03 The logical link control sub-layer management function group SAP: 
addresses to all network management entities on the system. 

AA The SNAP SAP: indicates that the next five bytes of a UI frame contain a 

SNAP identifier. 

FF The global SAP: broadcasts to all 802 receivers on a node. 



The IEEE has not yet assigned SAPs for Digital internal or customer use. 



Values for Ethernet and 802.3 Addressing 
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3 SNAP Identifiers 

The following SNAP identifier is reserved for Digital customer use: 
08-00-2B-60-06 

Digital reserves the following SNAP identifiers for internal use only: 

08-00-2B-60-MW 
08-00-2B-80-3C 
08-00-2B-80-3E 
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DLX Characteristics Status Codes 



This appendix lists the status codes for DLX characteristics and describes the con- 
ditions that return each code, noting any conditions unique to specific QIOs or 
characteristics blocks. 

Error codes have the prefix CE. and a negative 1 6-bit value. Full or partial success 
codes have the prefix CS. and a positive l6-bit value. CS.SUC (1) is the code for 
complete success; other CS. codes indicate partial success that may return unex- 
pected results. 



Table H-1 : Status Codes for DLX Characteristics 



CE. Codes 


Status 
Code 


Meaning 


Characteristic 


Explanation 


CE.ACN 
100012 


Address 
conflict 


CC 


MCT 


The protocol/address pair is already in 
use. 


CE.FMI 
100015 


Frame 
format 
invalid 


cc 
cc 


FMO or 
FMM 


You entered an invalid frame format 
value. The value must be NX$ETH or 
NX$802. 


CE.FMC 
100016 


Frame usage 
conflict 


cc 
cc 


FMO or 
FRM 


You specified both frame formats, but 
only one is valid. 






cc 
cc 
cc 
cc 


GSP, 
SCO, 
ISP, 
SNP 


The port is not enabled for 802.3 for- 
mat. 






cc 


GSP 


The port is not enabled for 802.3 for- 
mat with Class I service. 



(continued on next page) 
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Table H-1 (Cont.): Status Codes for DLX Characteristics 



CE. Codes (Cont.) 


Status 
Code 


Meaning 


Characteristic 


Explanation 


CE.IUN 
100013 


Invalid use 
of multicast 
address 


CC.DST 


You specified a multicast instead of a 
physical address. 


CE.MCE 
100007 


Multicast 

address 

enabled 


CC.MCT 


The specified multicast address is 
already enabled. 


CE.NMA 
100014 


Not a 

multicast 

address 


CC.MCT 


The multicast address you entered is 
not valid. Check that the least signifi- 
cant bit is 1 . 


CE.PCN 
100011 


Protocol 
conflict 


CC.DST 


In attempting to enable a protocol, 
your application: 

■ Attempted to enable itself as the 
default protocol user, but a default 
user already exists. 

■ Attempted to enable a protocol but 
an exclusive user for the protocol 
already exists. 

■ Attempted to enable an already- 
enabled protocol with a padding 
status that conflicts with its cur- 
rent status. The first request to 
enable a protocol type assigns the 
padding status to which all subse- 
quent uses of the protocol type 
conform. 


CE.RES 
100010 


Resource 

allocation 

failure 


Various 


No memory is available for the charac- 
teristics operation. 


CE.RTS 
100004 


Request too 
small 


Various, with 
lO.XGC 

Various, with 
lO.XSC 


You allocated too little space for the 
returned data. 

You supplied too little data. 


CE.RTL 
100003 


Request too 
large 


Various, with 
lO.XGC 

Various, with 
lO.XSC 


You allocated too much space for the 
returned data. 

You supplied too much data for the 
allocated space. 
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Table H-1 (Cont.): Status Codes for DLX Characteristics 



CE. Codes (Cont.) 


Status 
Code 


Meaning 


Characteristic 


Explanation 


CE.SNU 
100021 


SNAP in use 


CC.SNP 


Another port has already enabled the 
specified SNAP protocol identifier. 


CE.SPU 
100020 


SAP in use 


CC.ISP 


Another port has already enabled the 
specified SAP. 


CE.SRI 
100017 


Service class 
invalid 


cc.sco, 

CC.SRV 


You entered a value other than PF$CL1 
(10). 


CE.UDF 
100001 


Undefined 
function 


All 


The value in the C.TYPE field does not 
identify a valid characteristic type. 


CS. Codes 


CS.DAO 
000003 


Data overrun 


CC.DST with 
lO.XGC 

CC.SNP with 
lO.XGC 


Returned information exceeded allo- 
cated space. Ethernet protocol type 
information included more addresses 
than you allocated space for. 

SNAP protocol identifier information 
included more addresses than you allo- 
cated space for. 


CS.IGN 
000002 


Ignored 


All 


This code generally indicates that char- 
acteristics information was inappropri- 
ate. The code indicates various errors, 
including: your existing environment is 
incompatible with the characteristic 
type (in frame format, for example); the 
data you supplied was incomplete or 
incorrect for the characteristic; you 
already specified the characteristic and 
this is a redundant block. 


CS.SUC 
1 


Success 


All 


The characteristics block processed 
successfully. 
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Index 



A 

ABONCW, 1-15, 3-152, 3-l60 
Abort a logical link, 

seeABTx, ABT$, ABTNT 
Abort a task, 

5ee ABONCW 
ABT$, 2-12, 2-34 
ABTx, 1-9, 2-12, 3-13 
ABTNT, 3-13 
ACC$, 2-14 

Access control, 1-7, 2-23, 2-24, 2-45, 

2- 50, 3-5, 3-11, 3-12, 3-17, 

3- 18, 3-20, 3-21, 3-32, 3-41, 
3-155 

ACCNT, 3-2, 3-15 

Alias node names, 3-6 

ASCII string, 5-5 

ASCIZ strings, 3-93, 3-94 

Assigning logical unit numbers, 1-3, 1-8, 

1-10, 2-12, 2-14, 2-20, 2-40, 

3-2, 3-95, 5-4 
AST, 1-10, 2-63, 4-20 



B 

BACC, 3-7, 3-17 
BACCL, 3-20 
BACUSL, 3-155 



BACUSR, 3-157 
BFMTO, 3-23 
BMFTl, 3-25 

Buffering level, 3-89, 3-90 

Buffer space, 1-10, 2-43, 3-89, 3-91 

BUILD type macro, 2-1, 2-2 

c 

Characteristics status, 4-20 
Class I service, 4-15 
Closing files, 3-89 
Closing the network, 1-10, 3-2 
CLS$, 2-17 

CLSNFW, 3-89, 3-104, 3-107, 3-115 

CLSNT, 3-2, 3-89, 3-151 

CNAC$$, 2-28 

CN1D$$, 2-28 

CNPS$$, 2-28 

CON$,2-19 

CONB$$, 2-23 

CONL$$, 2-28 

Connect block, 1-6, 2-19, 2-21, 2-23, 

2- 24, 2-30, 2-36, 2-41, 3-17, 

3- 20, 3-37 

contents retrieved by GND$, 2-44 to 

2- 45 

contents retrieved by GNDNT (table), 

3- 45 to 3-48 
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Connect block (cont.) 
incoming, 2-5, 3-3 

and mail buffer size, 2-6 
short (table), 2-46, 2-47, 2-48, 2-49, 
2-50, 2-51 
length, 2-5, 2-41, 3-3, 3-42 
long, 2-28, 2-55 
short, 2-23 
Connect requests, 2-17, 2-55, 3-29 
CONNT, 3-2, 3-10, 3-23, 3-31 
Control field, 4-16 



DAP (Data Access Protocol), C-5, C-25 
DECnet, 

code definitions, D-1 

communication calls (table), 1-12, 1-13, 
1-14 

macro library (NETLIB.MLB), 4-3 

message types, 1-8 

remote file access operations, 1-14 

task control, 1-15 

tasks, 1-6 
Default mode (DLX), 4-13, 4-17 
DELNFW, 3-88, 3-105 
Destination descriptor, 1-6, 2-23, 2-28, 

3- 11, 3-12 
Direct line access controller, 

see DLX 
DIR$ macro, 2-2 

Disconnect or reject reason codes, A-1 
DLX, 4-1 

and Ethernet programming, 4-3 
characteristics, 

block (figure), 4-9 

buffer, 4-7 to 4- 11 

for Ethernet frame format (table), 

4- 14 

for 802.3 frame format (table), 4-18 
status, 4-20 

status codes, H-1 to H-3 
data segmentation and buffering, 4-2 
error recovery, 4-2 
Ethernet address, 4-5 
frame formats, 4-4 
multicast addressing, 4-5 



DLX (cont.) 

NX: device, 4-1 

padding support, 4-13 

physical addressing, 4-5 

protocol flags, 4-12,4-17 

protocol types, 4-12 

QIOs, 4-1, 4-20, 5-3 

QIO summary, 5-3 

status codes, 4-20 

synchronizing programs, 4-4 
DLX calls, 

lO.XCL, 5-16 

lO.XGC, 4-26 

lO.XHG, 5-14 

lO.XIN, 5-7 

lO.XOP, 4-21, 5-4 

lO.XRC, 4-47, 5-11 

lO.XSC, 4-25 

lO.XTM, 4-41, 5-9 
DLX characteristics, 

CC.ADR, 4-42, 4-49 

CC.CTM, 4-43,4-49 

CC.DAD, 4-50 

CC.DST, 4-26, 4-35 

CC.FMM, 4-44, 4-50 

CC.FMO, 4-22 

CC.FRM, 4-28 

CC.GSP, 4-29, 4-37 

CC.ISP, 4-29, 4-38 

CC.MCT, 4-30, 4-36 

CC.PRO, 4-44, 4-51 

CC.SCO, 4-23 

CC.SNM, 4-45,4-51 

CC.SNP, 4-30, 4-38 

CC.SPM, 4-45, 4-52 

CC.SRV, 4-32, 4-40 
DSC$, 2-34 
DSCNT, 3-35 



Error/Completion codes, 3-3, 3-32 

FORTRAN, COBOL, BASIC-PLUS-2, E-3 

MACRO-ll,F-l 

remote file access, C-1 

Establishing a network task, 3-2 

Ethernet address, 4-5 
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Event flags, 3-89, 4-20, 5-3 
Event flags,, 3-3 

Exclusive mode (DLX), 4-13,4-17 
EXECUTE type macro, 2-1, 2-2, 2-3, 2-5 
EXENFW, 3-88, 3-106 
Explicit connection, 6-2, 6-9 

F 

Flow control 

incoming messages, 2-15 

options, 1-10 

with DLX, 5-2 
Frame format, 

Ethernet, 4-12 

802.3,4-14 

G 

GETNFW, 3-89, 3-107 

GLN$, 2-36 

GLNNT, 3-37 

GND$, 2-15, 2-19, 2-39 

connect block (figure), 2-53 

mail buffer size, 2-6 
GNDa:, 1-8 
GNDNT, 3-31, 3-39 

mail buffer size, 3-5 

I 

Implicit connection, 6-10 
Interrupt message, 

receiving, 3-44 

sending, 1-8, 3-59, 2-66 
Intertask communication, 

calls, 1-2, 2-10, 3-1, 3-6, 3-9 

concepts, 1-2 

conventions, 1-2 

macros, 2-10 
lO.ATT, 6-8 
lO.DET, 6-10 
lO.HNG, 6-10 
IO.ORG, 6-2,6-9 
lO.RVB, 6-10 

I/O status blocks, 3-2, 4-20, 5-3 
lO.WVB, 6-10 



lO.XCL, 4-53 
lO.XGC, 4-33 
IS.DAO, 3-5 

L 

LAT 

definition, 6-1 

environment (figure), 6-2 

ports, 6-6 
LAT applications 

and LCP commands, 6-8 

attaching the terminal, 6-8 

directives (table), 6-12 

establishing the connection, 6-9 

preparing for, 6-8 

reading and writing data, 6-10 

setting characteristics, 6-9 

summary, 6-11 

terminating a connection, 6-10 
to queued services, 6-10 
see also individual directive names 
Libraries, 

MACRO-11 (NETLIB.MLB), 2-1, 4-3 
NETFOR.OLB, 3-1 
Links, 

data, 4-3 

logical, 1-4, 2-17, 2-55, 3-50 
Logical unit numbers (LUN), 

see Assigning logical unit numbers 

M 

Mail buffer, 

and incoming connect block, 2-6 

specifying length, 2-41 
mbxflg, 3-5 

MBXLU, 1-3, 2-54, 3-49 

N 

Network data queue, 1-2, 1-3, 1-7, 1-8, 

1-10, 2-17, 2-39 
Network File Access Routines (NFARs), 

3-89, 3-90, 3-91, 3-99 
NOFLOW option, 1-11,2-15,2-21 
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Non-ASCII data in connect block, 2-24, 
2-30 

NS: pseudodevice driver, 3-2 
NSSYM$ macro, A-1 
NT.LCB,2-55 
NT.LON, 2-41, 2-43 
NT.TYP, 2-41, 2-43 



o 

Object type codes, 3-23, B-1 
OPANFW, 3-88, 3-110, 3-114, 

3-115 
Open calls, 3-2 
Opening files, 3-88 
OPN$, 2-6, 2-54 
OPNNT, 3-2, 3-49, 3-151 
OPRNFW, 3-88, 3-1 10, 3-1 14 
OPWNFW, 3-88, 3-114, 3-120 
Originate explicit connection, 6-9 



P 

Parameters, 

for task build, 3-89 

overriding MACRO- 11,2-1, 2-3 

required for MACRO- 11,2-4 

PRGNFW, 3-89, 3-114, 3-115 

Protocol/address pairs, 4-13 
for 802. 3 format, 4-18 

Protocol flags (DLX), 4-17 

Proxy access, 3-6, 2-7 

with CONB$$ macro, 2-23 
with CONL$$ macro, 2-28 

/PR switch, 4-2 

PUTNFW, 3-89, 3-115 



Q 

QIO completion status, 4-20 

R 



Records, 

writing, 3-115, 3-120 
REJ$, 2-59 

Reject reason codes, A-1 
REJNT, 3-54 
Remote file access, 

argument definitions, 3-94 

buffer space, 3-91 

calls, 3-1, 3-2, 3-6 

calls (table), 3-87 

closing files, 3-89 

concepts, 1-1, 1-14, 1-15 

opening files, 3-88 

task build parameters, 3-91 
Remote task control, 1-1, 1-15, 3-151 
RENNFW, 3-88 

s 

SAPs, 4-16 

Scheduling a task for execution, 1-15, 
3-159 

Send an interrupt message, 

see Interrupt message 
Send data, 

see SND$, SNDNT 
Service Access Points (SAPs), 4-16 
Service names, 6-6 
SET PORT command, 6-9 
SF.GMC, 6-16 
SF.SMC, 6-9, 6-19 
SNAP identifiers, 4-16 
SND$, 2-61 
SNDNT, 3-56 

SOURCE DESCRIPTOR, 2-47 
Source descriptor, 1-6, 2-49 
SPA$, 2-39, 2-63 
SPLNFW, 3-88, 3-114, 3-120 
Spool or print a file, 

see SPLNFW 
STACK type macro, 2-1, 2-4, 2-5 
Subnetwork Access Protocols (SNAPs), 4-16 
SUBNFW, 3-88, 3-114, 3-120, 3-121 



Readingafile, 3-88, 3-107, 3-110 j 
REC$, 2-57 

RECNT, 3-52 Task, 
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Task, (cont.) 

aborting, 

seeABONCW 

communicating with remote task, 
see Intertask communication 

scheduling, 
see RUNNCW 
Task building DLX programs, 

/PR switch, 4-2 
Task control block, 3-153, 3-160 
Task control utility, 3-151 
Task-to-task communication, 

using DLX, 4-1 
TC.MAP characteristic 

with SF.GMC, 6-17 

with SF.SMC, 6-20 
TC.QDP characteristic, 6-18 
Terminal servers, 6-6 

port names, 6-6 
Terminating LAT connections, 6-10 

u 

User abort, 

seeABT$, ABTNT, GND$, GNDNT 
User disconnect, 

seenzmes, 1-7 

w 

WAITNT, 1-10, 3-58 
Wait options, 1-10 

X 

XMU, 2-66 
XMINT, 3-59 



802.3 frame format, 
service class, 4-15 



HOW TO ORDER ADDITIONAL DOCUMENTATION 



DIRECT TELEPHONE ORDERS 



ELECTRONIC ORDERS (U.S. ONLY) 



Dial 800-DEC-DEMO with any VTIOO or VT200 
compatible terminal and a 1200 baud modem. 
If you need assistance, call 1-800-DIGITAL. 



DIRECT MAIL ORDERS (U.S. and Puerto Rico*) 



DIGITAL EQUIPMENT CORPORATION 
P.O. Box CS2008 
Nashua, New Hampshire 03061 



DIRECT MAIL ORDERS (Canada) 



DIGITAL EQUIPMENT OF CANADA LTD. 
940 Belfast Road 
Ottawa, Ontario, Canada K1G 4C2 
Attn: A&SG Business Manager 



INTERNATIONAL 



DIGITAL 
EQUIPMENT CORPORATION 
A&SG Business Manager 
c/o Digital's local subsidiary 
or approved distributor 



Internal orders should be placed through the Software Distribution Center (SDC), 
Digital Equipment Corporation, Westminster, Massachusetts 01473 



* Any prepaid order from Puerto Rico must be placed 
with the Local Digital Subsidiary: 
809-754-7575 



In Continental USA 
and Puerto Rico 
call 800-258-1710 



In Canada 

call 800-267-61 46 



In New Hampshire 
Alaska or Hawaii 
call 603-884-6660 
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